@stepzen/sdk 0.0.0-experimental-20221114-610843f6

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@stepzen/sdk",
+  "version": "0.0.0-experimental-20221114-610843f6",
+  "license": "MIT",
+  "author": "Darren Waddell <darren@stepzen.com>",
+  "homepage": "https://stepzen.com",
+  "files": [
+    "lib/**/*",
+    "src/**/*"
+  ],
+  "engines": {
+    "node": ">=14.0.1",
+    "npm": ">=6.14"
+  },
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "scripts": {
+    "clean": "rm -rf lib tsconfig.tsbuildinfo",
+    "build": "../../node_modules/.bin/tsc -b",
+    "test": "npm run build && nyc --extension .ts mocha --config test/mocha.opts.json",
+    "test:single": "npm run build && mocha --config test/mocha.opts.json",
+    "posttest": "prettier . --check"
+  },
+  "dependencies": {
+    "@stepzen/fetch": "^0.0.0-experimental-20221114-610843f6",
+    "@stepzen/transpiler": "^0.0.0-experimental-20221114-610843f6",
+    "archiver": "^5.3.0",
+    "debug": "^4.3.4",
+    "dotenv": "^16.0.1",
+    "form-data": "^4.0.0",
+    "fs-extra": "^10.0.1",
+    "glob": "^7.2.0",
+    "is-wsl": "^2.2.0",
+    "yaml": "^1.10.2"
+  },
+  "devDependencies": {
+    "@types/archiver": "^5.1.0",
+    "@types/debug": "^4.1.5",
+    "@types/fs-extra": "^9.0.12",
+    "@types/glob": "^7.1.3",
+    "@types/license-checker": "^25.0.1",
+    "@types/mocha": "^8.2.2",
+    "chai": "^4.3.4",
+    "fancy-test": "^1.4.10",
+    "license-checker": "^25.0.1",
+    "mocha": "^8.3.2",
+    "nyc": "^15.1.0",
+    "prettier": "^2.5.1",
+    "ts-node": "^10.8.2"
+  },
+  "gitHead": "956064c78cdc0cdcfa085a34ab3d9267bd08e649"
+}

package/src/client-v2.ts

@@ -0,0 +1,120 @@
+// Copyright (c) 2020,2021,2022, StepZen, Inc.
+
+import accountCmd from './commands-v2/account'
+import deployCmd from './commands-v2/deploy'
+import listEndpointsCmd from './commands-v2/list'
+import getPublicAccount from './commands-v2/getPublicAccount'
+import {
+  generateConfigurationPayload,
+  generateSchemaFilesPayload,
+} from './shared/payloads'
+import {SDKConfigurationV2} from './shared/types'
+
+export const ensureValidCredentials = async (
+  auth:
+    | {account: string; adminKey: string; deploymentType: string}
+    | {publicAccountToken: string; deploymentType: string},
+  sdkConfig: SDKConfigurationV2,
+) => {
+  let credentials
+
+  if ('publicAccountToken' in auth) {
+    // create an anonymous account and use it to initialize an SDK client instance
+    const {data, error} = await getPublicAccount({
+      token: auth.publicAccountToken,
+      deploymentType: auth.deploymentType,
+      sdkConfig,
+    })
+
+    if (error) {
+      throw new Error(`An unexpected error occurred: ${error.message}`)
+    }
+
+    credentials = data
+  } else {
+    // use the provided account to initialize an SDK client instance
+    const {data, error} = await accountCmd({
+      account: auth.account,
+      adminKey: auth.adminKey,
+      deploymentType: auth.deploymentType,
+      sdkConfig,
+    })
+
+    if (error) {
+      throw new Error(error.message)
+    }
+
+    credentials = data
+  }
+
+  return credentials
+}
+
+export const createSdkClient = async (
+  auth:
+    | {account: string; adminKey: string; deploymentType: string}
+    | {publicAccountToken: string; deploymentType: string},
+  sdkConfig: SDKConfigurationV2,
+) => {
+  const credentials = await ensureValidCredentials(auth, sdkConfig)
+
+  return {
+    get credentials(): typeof credentials {
+      // always return a copy to avoid accidential modification by the caller
+      return {...credentials}
+    },
+    /**
+     * Create or update a GraphQL endpoint at StepZen.
+     * The URL of the endpoint is formed as {StepZen instance URL}/{folder}/{name}/__graphql
+     * e.g. https://account.stepzen.net/api/users/__graphql
+     *
+     * @param folder - folder name (e.g. `api`); will be a part of the endpoint URL
+     * @param name - endpoint name (e.g. `users`); will be a part of the endpoint URL
+     * @param directory - full path to a GraphQL schema directory (should have `index.graphql` in it)
+     * @param config - full path to a config `.yml` file
+     * @param public - whether or not to allow public access to the endpoint (`false` by default)
+     * @returns details of the created / updated endpoint
+     */
+    deploy: async ({
+      folder,
+      name,
+      directory,
+      config,
+      public: _public = false,
+    }: {
+      folder: string
+      name: string
+      directory: string
+      config?: string
+      public?: boolean
+    }) => {
+      return deployCmd({
+        account: credentials.account,
+        adminKey: credentials.adminKey,
+        deploymentType: credentials.deploymentType,
+        endpointName: name,
+        endpointType: 'dev',
+        folderName: folder,
+        public: _public,
+        schemaFiles: generateSchemaFilesPayload(directory),
+        configuration: await generateConfigurationPayload(config),
+        sdkConfig,
+      })
+    },
+    list: {
+      /**
+       * List deployed endpoints.
+       *
+       * @returns list of deployed endpoints
+       */
+      endpoints: () => {
+        return listEndpointsCmd({
+          account: credentials.account,
+          adminKey: credentials.adminKey,
+          deploymentType: credentials.deploymentType,
+          sdkConfig,
+        })
+      },
+    },
+  }
+}

package/src/client.ts

@@ -0,0 +1,133 @@
+// Copyright (c) 2020,2021,2022, StepZen, Inc.
+
+import accountCommand from './commands/account'
+import deploy from './commands/deploy'
+import {
+  AnonymousClientOptions,
+  SDKConfiguration,
+  StepZenAccount,
+} from './shared/types'
+import list from './commands/list'
+import upload from './commands/upload'
+import getPublicAccount from './commands/getPublicAccount'
+
+export * from './shared/types'
+
+export const validateCreateClientOptions = async (
+  options: StepZenAccount | Required<AnonymousClientOptions>,
+  sdkConfig: SDKConfiguration,
+) => {
+  let credentials
+  let account
+
+  if ('publicAccountToken' in options) {
+    // create an anonymous account and use it to initialize an SDK client instance
+    const credentialsOrError = await getPublicAccount(options, sdkConfig)
+    if ('errors' in credentialsOrError) {
+      throw new Error(
+        `An unexpected error occurred. ${JSON.stringify(
+          credentialsOrError.errors,
+        )}`,
+      )
+    }
+
+    credentials = credentialsOrError
+    account = {
+      ...credentialsOrError,
+      server: options.server,
+      domain: options.domain,
+    }
+  } else {
+    // use the provided account to initialize an SDK client instance
+    options.server = options.server.replace('{account}', options.account)
+    let accountOrError
+    try {
+      accountOrError = await accountCommand(options, sdkConfig)
+    } catch (error) {
+      if (
+        error instanceof Error &&
+        error.message.includes('Please check your authentication details')
+      ) {
+        throw new Error('Your credentials are invalid.')
+      } else {
+        throw new Error(`An unexpected error occurred. ${error}`)
+      }
+    }
+
+    if ('errors' in accountOrError) {
+      throw new Error(
+        `An unexpected error occurred. ${JSON.stringify(
+          accountOrError.errors,
+        )}`,
+      )
+    }
+
+    account = options
+
+    credentials = {
+      account: options.account,
+      adminkey: options.adminkey,
+      apikey: accountOrError.apikey,
+    }
+  }
+  return {account, credentials}
+}
+
+export const createSdkClient = async (
+  options: Required<StepZenAccount | AnonymousClientOptions>,
+  sdkConfig: SDKConfiguration,
+) => {
+  const {account, credentials} = await validateCreateClientOptions(
+    options,
+    sdkConfig,
+  )
+
+  return {
+    get credentials(): typeof credentials {
+      // always return a copy to avoid accidential modification by the caller
+      return {...credentials}
+    },
+    /**
+     * @deprecated use `.credentials` or create a new SDK client instead
+     **/
+    account: () => {
+      return accountCommand(account, sdkConfig)
+    },
+    deploy: (
+      destination: string,
+      properties: {
+        configurationsets?: string[]
+        schema: string
+      },
+    ) => {
+      return deploy({destination, ...properties}, account, sdkConfig)
+    },
+    list: {
+      deployments: async () => {
+        return list({type: 'deployments'}, account, sdkConfig)
+      },
+      configurationsets: async () => {
+        return list({type: 'configurationsets'}, account, sdkConfig)
+      },
+      schemas: async () => {
+        return list({type: 'schemas'}, account, sdkConfig)
+      },
+    },
+    upload: {
+      configurationset: async (destination: string, file: string) => {
+        return upload(
+          {type: 'configurationset', destination, file},
+          account,
+          sdkConfig,
+        )
+      },
+      schema: async (destination: string, directory: string) => {
+        return upload(
+          {type: 'schema', destination, directory},
+          account,
+          sdkConfig,
+        )
+      },
+    },
+  }
+}

package/src/commands/account.ts

@@ -0,0 +1,54 @@
+// Copyright (c) 2020,2021,2022, StepZen, Inc.
+
+import * as debug from 'debug'
+import fetch from '@stepzen/fetch'
+
+import {ADMIN_ACCOUNT_URL} from '../shared/constants'
+import {getRequestHeaders} from '../shared/request'
+import {SDKConfiguration, StepZenAccount} from '../shared/types'
+
+export default async (
+  account: StepZenAccount,
+  sdkConfig: SDKConfiguration,
+): Promise<
+  {account: string; apikey: string} | {success: false; errors: string[]}
+> => {
+  const headers = getRequestHeaders(account, sdkConfig)
+  const url = `${account.server}${ADMIN_ACCOUNT_URL}`
+
+  debug('stepzen:headers')(headers)
+
+  const response = await fetch(url, {
+    headers: headers as any,
+    method: 'POST',
+  })
+
+  debug('stepzen:response')(response)
+
+  if (response.status === 401 || response.status === 403) {
+    throw new Error(
+      'Could not complete the request. Please check your authentication details are correct.',
+    )
+  }
+
+  if (response.status >= 400) {
+    return {
+      errors: [response.statusText],
+      success: false,
+    }
+  }
+
+  const text = await response.text()
+  let json
+
+  try {
+    json = JSON.parse(text)
+  } catch {
+    return {
+      errors: [`An unexpected error occurred.\n\n${text}`],
+      success: false,
+    }
+  }
+
+  return json
+}

package/src/commands/authenticate.ts

@@ -0,0 +1,30 @@
+// Copyright (c) 2020,2021,2022, StepZen, Inc.
+
+import * as debug from 'debug'
+import fetch from '@stepzen/fetch'
+
+import {ADMIN_VERIFY_URL} from '../shared/constants'
+import {getRequestHeaders} from '../shared/request'
+import {SDKConfiguration, StepZenAccount} from '../shared/types'
+
+export default async (
+  settings: StepZenAccount,
+  sdkConfig: SDKConfiguration,
+): Promise<boolean> => {
+  const headers = getRequestHeaders(settings, sdkConfig)
+  const url = `${settings.server}${ADMIN_VERIFY_URL}`
+
+  debug('stepzen:headers')(headers)
+  debug('stepzen:url')(url)
+
+  try {
+    const response = await fetch(url, {
+      headers: headers as any,
+      method: 'POST',
+    })
+    await response.json()
+    return true
+  } catch {
+    return false
+  }
+}

package/src/commands/deploy.ts

@@ -0,0 +1,72 @@
+// Copyright (c) 2020,2021,2022, StepZen, Inc.
+
+import * as debug from 'debug'
+import fetch from '@stepzen/fetch'
+
+import {ADMIN_DEPLOY_URL} from '../shared/constants'
+import {getRequestHeaders} from '../shared/request'
+import {
+  SDKConfiguration,
+  StepZenAccount,
+  StepZenDeploy,
+  ZenCtlResponse,
+} from '../shared/types'
+
+export default async (
+  details: StepZenDeploy,
+  account: StepZenAccount,
+  sdkConfig: SDKConfiguration,
+): Promise<ZenCtlResponse> => {
+  const headers = getRequestHeaders(account, sdkConfig)
+
+  const payload: any = {
+    schema: `/workspaces/schemas/${details.schema}`,
+  }
+
+  if (details.configurationsets) {
+    payload.configurationsets = details.configurationsets.map(
+      config => `/workspaces/configurationsets/${config}`,
+    )
+  }
+
+  debug('stepzen:headers')(headers)
+  debug('stepzen:payload')(payload)
+
+  const response = await fetch(
+    `${account.server}${ADMIN_DEPLOY_URL}/${details.destination}`,
+    {
+      body: JSON.stringify(payload),
+      headers: headers as any,
+      method: 'POST',
+    },
+  )
+
+  debug('stepzen:response')(response)
+
+  if (response.status >= 400 && response.status < 500) {
+    throw new Error(
+      'Could not complete the request. Please check your authentication details are correct.',
+    )
+  }
+
+  if (response.status >= 500) {
+    return {
+      errors: [response.statusText],
+      success: false,
+    }
+  }
+
+  const text = await response.text()
+  let json
+
+  try {
+    json = JSON.parse(text)
+  } catch {
+    return {
+      errors: [`An unexpected error occurred.\n\n${text}`],
+      success: false,
+    }
+  }
+
+  return json
+}

package/src/commands/getPublicAccount.ts

@@ -0,0 +1,77 @@
+// Copyright (c) 2020,2021,2022, StepZen, Inc.
+
+import * as debug from 'debug'
+import fetch from '@stepzen/fetch'
+
+import {getUserAgent} from '../shared/request'
+import {
+  AnonymousClientOptions,
+  SDKConfiguration,
+  StepZenCredentials,
+} from '../shared/types'
+
+export default async (
+  options: Required<AnonymousClientOptions>,
+  sdkConfig: SDKConfiguration,
+): Promise<
+  | StepZenCredentials
+  | {
+      success: false
+      errors: string[]
+    }
+> => {
+  const account = process.env.STEPZEN_PUBLIC_ACCOUNT_API_ACCOUNT || 'stepzen'
+  const endpoint =
+    process.env.STEPZEN_PUBLIC_ACCOUNT_API_ENDPOINT || 'api/publicaccount'
+  const server = options.server
+    .replace('{account}', account)
+    .replace('.io', '.net')
+
+  const url = new URL(`${server}/${endpoint}/__graphql`)
+  // Inlclude the token into the URL so that it is visible in the logs
+  // (allows StepZen to do analytics based on the GCP logs).
+  url.searchParams.set('token', options.publicAccountToken)
+
+  try {
+    debug('stepzen:createAnonymousAccount')(url)
+    const response = await fetch(url, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'User-Agent': getUserAgent(sdkConfig),
+      },
+      body: JSON.stringify({
+        query: `query (
+            $token: String!
+          ) {
+            getAccountDetails(
+              token: $token
+            ) {
+              account: accountName
+              adminkey: adminKey
+              apikey: apiKey
+            }
+          }`,
+        variables: {
+          token: options.publicAccountToken,
+        },
+      }),
+    })
+    const json = await response.json()
+    debug('stepzen:createAnonymousAccount')(json)
+    if (json.errors) {
+      return {
+        success: false,
+        errors: json.errors,
+      }
+    }
+
+    if (!json.data?.getAccountDetails) {
+      throw new Error('No data returned from the API endpoint.')
+    }
+
+    return json.data?.getAccountDetails
+  } catch (error) {
+    throw new Error(`Could not create a public account (${error})`)
+  }
+}

package/src/commands/list.ts

@@ -0,0 +1,50 @@
+// Copyright (c) 2020,2021,2022, StepZen, Inc.
+
+import * as debug from 'debug'
+import fetch from '@stepzen/fetch'
+
+import {ADMIN_LIST_URL} from '../shared/constants'
+import {getRequestHeaders} from '../shared/request'
+import {
+  SDKConfiguration,
+  StepZenAccount,
+  StepZenList,
+  ZenCtlResponse,
+} from '../shared/types'
+
+export default async (
+  details: StepZenList,
+  account: StepZenAccount,
+  sdkConfig: SDKConfiguration,
+): Promise<ZenCtlResponse> => {
+  const headers = getRequestHeaders(account, sdkConfig)
+
+  debug('stepzen:headers')(headers)
+
+  const response = await fetch(
+    `${account.server}${ADMIN_LIST_URL}/${details.type}`,
+    {
+      headers: headers as any,
+      method: 'GET',
+    },
+  )
+
+  debug('stepzen:response')(response)
+
+  if (response.status >= 400 && response.status < 500) {
+    throw new Error(
+      'Could not complete the request. Please check your authentication details are correct.',
+    )
+  }
+
+  const text = await response.text()
+  let json
+
+  try {
+    json = JSON.parse(text)
+  } catch {
+    throw new Error(`An unexpected error occurred.\n\n${text}`)
+  }
+
+  return json
+}

package/src/commands/upload.ts

@@ -0,0 +1,91 @@
+// Copyright (c) 2020,2021,2022, StepZen, Inc.
+
+import * as debug from 'debug'
+import fetch from '@stepzen/fetch'
+
+import {ADMIN_UPLOAD_URL} from '../shared/constants'
+import {generateYamlPayload, generateZipPayload} from '../shared/payloads'
+import {getRequestHeaders} from '../shared/request'
+import {
+  SDKConfiguration,
+  StepZenAccount,
+  StepZenUpload,
+  ZenCtlResponse,
+} from '../shared/types'
+import {transpileConfigurationset} from '../shared/transpiling'
+import {validateConfigurationset, validateSchema} from '../shared/validation'
+
+export default async (
+  details: StepZenUpload,
+  account: StepZenAccount,
+  sdkConfig: SDKConfiguration,
+): Promise<ZenCtlResponse> => {
+  const headers = getRequestHeaders(account, sdkConfig)
+  let payload
+
+  switch (details.type) {
+    case 'configurationset':
+      await validateConfigurationset(details.file)
+      const transpiled = await transpileConfigurationset(details.file!)
+      debug('stepzen:sdk')(`effective config written to ${transpiled}`)
+      payload = await generateYamlPayload(transpiled)
+      break
+
+    case 'schema':
+      await validateSchema(details.directory)
+      payload = await generateZipPayload(
+        details.directory,
+        {
+          destination: details.destination,
+          stitcherName: 'index.graphql',
+        },
+        [/.*\.graphql$/i],
+      )
+      break
+  }
+
+  debug('stepzen:headers')(headers)
+  debug('stepzen:payload')(payload)
+
+  const response = await fetch(
+    `${account.server}${ADMIN_UPLOAD_URL}/${details.type}/${details.destination}`,
+    {
+      body: payload,
+      headers: headers as any,
+      method: 'POST',
+    },
+  )
+
+  debug('stepzen:response')(response)
+
+  if (response.status >= 400 && response.status < 500) {
+    return {
+      message:
+        'Could not complete the request. Please check your authentication details are correct.',
+      success: false,
+    }
+  }
+
+  if (response.status >= 500) {
+    return {
+      errors: ['Internal Server Error'],
+      message: response.statusText,
+      success: false,
+    }
+  }
+
+  const text = await response.text()
+  let json
+
+  try {
+    json = JSON.parse(text)
+  } catch {
+    return {
+      errors: [`An unexpected error occurred.\n\n${text}`],
+      message: `An unexpected error occurred.\n\n${text}`,
+      success: false,
+    }
+  }
+
+  return json
+}