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

package/src/shared/payloads.ts

@@ -0,0 +1,153 @@
+// Copyright (c) 2020,2021,2022, StepZen, Inc.
+
+// This file contains helpers that zip a file or directory
+
+import * as archiver from 'archiver'
+import * as debug from 'debug'
+import * as FormData from 'form-data'
+import * as fs from 'fs'
+import * as glob from 'glob'
+import * as os from 'os'
+import * as path from 'path'
+import * as yaml from 'yaml'
+import {transpileConfigurationset} from './transpiling'
+import {validateConfigurationset} from './validation'
+import {Configuration, SchemaFiles} from './types'
+
+type YamlPayload = FormData
+type ZipPayload = FormData
+
+// This function takes a (yaml) file path
+// and creates a FormData payload, containing the yaml content as 'yaml'
+export const generateYamlPayload = async (
+  file: string | undefined,
+): Promise<YamlPayload> => {
+  return new Promise((resolve, reject) => {
+    const payload = new FormData()
+
+    if (file) {
+      if (!fs.existsSync(file)) {
+        reject(new Error(`File does not exist: ${file}`))
+      }
+      const content = fs.readFileSync(file, 'utf8')
+      debug('stepzen:sdk:payload')(`adding YAML payload\n${content}`)
+      payload.append('yaml', fs.readFileSync(file))
+      resolve(payload)
+    } else {
+      reject(new Error('File not specified'))
+    }
+  })
+}
+
+// This function takes a directory path, and optional data object,
+// and creates a FormData payload, containing the directory contents as 'zip',
+// and any other items in the data object.
+export const generateZipPayload = async (
+  directory: string | undefined,
+  data: object | undefined,
+  filters: RegExp[],
+): Promise<ZipPayload> => {
+  return new Promise((resolve, reject) => {
+    const payload = new FormData()
+
+    if (data) {
+      for (const [key, value] of Object.entries(data)) {
+        payload.append(key, value)
+      }
+    }
+
+    // Store it in /tmp. Create a WriteStream
+    const filepath = path.join(os.tmpdir(), `stepzen-payload-${Date.now()}.zip`)
+    const output = fs.createWriteStream(filepath)
+
+    // We're making a zip file
+    const archive = archiver('zip', {
+      zlib: {level: 9},
+    })
+
+    // We're piping it to the WriteStream
+    archive.pipe(output)
+
+    // If we've specified a directory, add it to the archive
+    if (directory) {
+      if (!fs.existsSync(directory)) {
+        reject(new Error(`Directory does not exist: ${directory}`))
+      }
+
+      // Get all the files in the directory (and all subdirectories).
+      const allFiles = glob.sync('**', {cwd: directory})
+
+      // Loop through each file, because we want to filter them
+      // We add them manually, because when we use glob, it embeds
+      // a full path, and we want everything to explicitly
+      // start at the root of the archive.
+      allFiles.forEach(file => {
+        const include = filters.some(filter => file.match(filter))
+
+        if (include) {
+          debug('stepzen:archive')(file)
+          archive.file(path.join(directory, file), {name: file})
+        }
+      })
+    }
+
+    // Once we're done, append a ReadStream to the tmp file
+    output.on('close', () => {
+      const stream = fs.createReadStream(filepath)
+      payload.append('zip', stream)
+      // Remove the temporary zip
+      stream.on('close', () => {
+        fs.unlinkSync(filepath)
+      })
+      // This is where we return the payload
+      resolve(payload)
+    })
+
+    // Archive the file or directory
+    archive.finalize()
+  })
+}
+
+export const generateSchemaFilesPayload = (
+  workspaceFolderPath: string,
+): SchemaFiles => {
+  if (!fs.existsSync(workspaceFolderPath)) {
+    throw new Error(
+      `Failed to read folder ${workspaceFolderPath}. Does it exist?`,
+    )
+  }
+
+  const files = glob
+    .sync('**/*.graphql', {cwd: workspaceFolderPath})
+    .map(file => {
+      return {
+        name: file,
+        content: fs.readFileSync(`${workspaceFolderPath}/${file}`, 'utf8'),
+      }
+    })
+
+  if (files.length === 0) {
+    throw new Error(
+      `Failed to find any .graphql files in ${workspaceFolderPath}`,
+    )
+  }
+
+  return {
+    files,
+    entryPoint: 'index.graphql',
+  }
+}
+
+export const generateConfigurationPayload = async (
+  configFilePath?: string,
+): Promise<Configuration | null> => {
+  if (!configFilePath) {
+    return null
+  }
+
+  await validateConfigurationset(configFilePath)
+  const transpiled = await transpileConfigurationset(configFilePath)
+  debug('stepzen:sdk')(`effective config written to ${transpiled}`)
+  const content = fs.readFileSync(transpiled, 'utf-8')
+  return yaml.parse(content, {schema: 'failsafe'}) || null
+}

package/src/shared/request.ts

@@ -0,0 +1,28 @@
+// Copyright (c) 2020,2021,2022, StepZen, Inc.
+
+import * as os from 'os'
+import * as isWsl from 'is-wsl'
+import {SDKConfiguration, StepZenAccount, ZenCtlRequestHeaders} from './types'
+
+const {version} = require('../../package.json')
+
+// mimics the logic from @oclif/config
+// https://github.com/oclif/core/blob/d7067d13c7d80c9e0064455c27ac1ebb6ee53fd2/src/config/config.ts#L128
+const arch = os.arch() === 'ia32' ? 'x86' : (os.arch() as any)
+const platform = isWsl ? 'wsl' : (os.platform() as any)
+
+export const getUserAgent = (sdkConfig: SDKConfiguration): string => {
+  return `${sdkConfig.appName} stepzen-sdk/${version} (${platform}; ${arch}; node-${process.version})`
+}
+
+export const getRequestHeaders = (
+  account: StepZenAccount,
+  sdkConfig: SDKConfiguration,
+): ZenCtlRequestHeaders => {
+  return {
+    authorization: `Apikey ${account.adminkey}`,
+    host: `${account.account}.${account.domain}`,
+    'stepzen-cli-version': version,
+    'user-agent': getUserAgent(sdkConfig),
+  }
+}

package/src/shared/transpiling.ts

@@ -0,0 +1,49 @@
+// Copyright (c) 2020,2021,2022, StepZen, Inc.
+
+import * as dotenv from 'dotenv'
+import * as debug from 'debug'
+import * as fs from 'fs-extra'
+import * as os from 'os'
+import * as path from 'path'
+import {transpile} from '@stepzen/transpiler'
+
+/**
+ * @returns `undefined` when called without arguments
+ */
+export async function transpileConfigurationset(): Promise<undefined>
+
+/**
+ * Strip off any unsupported properties and substitute any STEPZEN_*
+ * placeholders with matching environment variables (load a `.env` file
+ * if present next to the `config.yaml` file).
+ *
+ * @param file path to a `config.yaml` file
+ * @returns path to a temp copy of `config.yaml` file with all clean-up
+ *    and substitutions made
+ */
+export async function transpileConfigurationset(file: string): Promise<string>
+
+export async function transpileConfigurationset(file?: string) {
+  if (!file) {
+    return
+  }
+
+  const source = file.substring(0, file.lastIndexOf('/'))
+  debug('stepzen:dotenv')(
+    `loading .env from ${path.resolve(source)}` +
+      `, at sdk/src/shared/transpiling.ts`,
+  )
+  dotenv.config({path: path.resolve(source, '.env')})
+
+  const tmp = path.join(os.tmpdir(), `stepzen-transpiler-${Date.now()}`)
+  const configPath = path.join(tmp, 'config.yaml')
+
+  fs.ensureDirSync(tmp)
+  fs.copyFileSync(file, configPath)
+
+  const result = await transpile(tmp)
+
+  fs.emptyDirSync(tmp)
+  fs.writeFileSync(configPath, result.config || '')
+  return configPath
+}

package/src/shared/types.ts

@@ -0,0 +1,235 @@
+// Copyright (c) 2020,2021,2022, StepZen, Inc.
+
+export interface StepZenAccount {
+  account: string
+  adminkey: string
+
+  /**
+   * ZenCtl base URL, e.g. `https://fakefish.stepzen.io` for production,
+   * or `http://localhost` for local tests.
+   *
+   * Determined by taking the first option that is defined:
+   *  - the `server` config property explicily passed into the `init()` function
+   *  - the `STEPZEN_SERVER_URL` environment variable
+   *  - the `https://{account}.stepzen.io` default value
+   *
+   * The `{account}` placeholder (if present) is replaced by the provided account
+   * name
+   */
+  server: string
+
+  /**
+   * ZenCtl domain, e.g. `stepzen.io`. This is only relevant for local testing
+   * when ZenCtl is running on localhost. In that case an additional `Host` HTTP
+   * header is added to requests, using a non-localhost host name constructed
+   * from this property.
+   *
+   * Determined by taking the first option that is defined:
+   *  - the `domain` config property explicily passed into the `init()` function
+   *  - the `STEPZEN_DOMAIN` environment variable
+   *  - the `stepzen.io` default value
+   */
+  domain: string
+}
+
+export type StepZenCredentials = {
+  account: string
+  adminkey: string
+  apikey: string
+}
+
+export type UserCredentialsClientOptions = Pick<
+  StepZenAccount,
+  'account' | 'adminkey'
+> &
+  Partial<StepZenAccount>
+
+export type AnonymousClientOptions = {
+  publicAccountToken: string
+  server?: StepZenAccount['server']
+  domain?: StepZenAccount['domain']
+}
+
+export interface StepZenDeploy {
+  configurationsets?: string[]
+  destination: string
+  schema: string
+}
+
+export interface StepZenList {
+  type: 'deployments' | 'schemas' | 'configurationsets'
+}
+
+export interface StepZenUpload {
+  destination: string
+  directory?: string
+  file?: string
+  type: string
+}
+
+export interface ZenCtlRequestHeaders {
+  authorization: string
+  host: string
+  'stepzen-cli-version': string
+  'user-agent': string
+}
+
+export interface ZenCtlResponse {
+  errors?: Array<string>
+  message?: string
+  results?: Array<string>
+  success: boolean
+}
+
+export interface SDKConfiguration {
+  /**
+   * The name and version of that app that uses the SDK,
+   * e.g. `stepzen-cli/0.9.32`
+   *
+   * It is appended to the user-agent string in all requests made to StepZen
+   * through the SDK and becomes availabe in the log analytics.
+   */
+  appName: string
+}
+
+export interface SDKConfigurationV2 extends SDKConfiguration {
+  /**
+   * The name and version of that app that uses the SDK,
+   * e.g. `stepzen-cli/0.9.32`
+   *
+   * It is appended to the user-agent string in all requests made to StepZen
+   * through the SDK and becomes availabe in the log analytics.
+   */
+  appName: string
+
+  /**
+   * Version of ZenCtl API to use:
+   *  - `undefined`, `v1`: implies the v1 REST API at /ctl/admin/
+   *  - `v2`: implies the v2 GraphQL API
+   */
+  apiVersion: string
+
+  /**
+   * URL of the ZenCtl GraphQL API,
+   * e.g. https://stepzen.stepzen.net/api/zenctl2/__graphql
+   */
+  zenctlApiUrl: string
+
+  /**
+   * URL of the StepZen getPublicAccount GraphQL API,
+   * e.g. https://stepzen.stepzen.net/api/publicaccount/__graphql
+   */
+  publicAccountApiUrl: string
+}
+
+export interface ZenCtlSuccessResponseV2<T> {
+  data: T
+  error: undefined
+}
+
+export interface ZenCtlErrorResponseV2 {
+  data: undefined
+  error: {
+    message: string
+  }
+}
+
+export type ZenCtlResponseV2<T> =
+  | ZenCtlSuccessResponseV2<T>
+  | ZenCtlErrorResponseV2
+
+export interface StepZenCredentialsV2 {
+  account: string
+  adminKey: string
+  apiKeys: string[]
+  deploymentType: string
+}
+
+export interface StepZenAccountV2 {
+  account: string
+  ownerEmail: string
+  adminKey: string
+  apiKeys: string[]
+  deploymentType: string
+}
+
+export interface StepZenEndpointV2 {
+  account: string
+  deploymentType: string
+  folderName: string
+  endpointName: string
+  public: boolean
+  endpointType: string
+}
+
+export interface SchemaFiles {
+  files: SchemaFile[]
+  entryPoint?: String
+}
+
+export interface SchemaFile {
+  name: string
+  content: string
+}
+
+export interface Configuration {
+  configurationset?: ConfigurationSet[]
+  ruleset?: QueryRule[]
+  access?: Policies
+  deployment?: DeploymentSettings
+}
+
+export interface ConfigurationSet {
+  configuration?: Record<string, any>
+}
+
+export interface QueryRule {
+  query: string
+  disabled?: boolean
+  rules?: Rule[]
+}
+
+export interface Rule {
+  predicate: string
+  action: string
+}
+
+export interface Policies {
+  policies?: Policy[]
+}
+
+export interface Policy {
+  type?: string
+  rules?: FieldRule[]
+  policyDefault?: FieldCondition
+}
+
+export interface FieldRule {
+  name?: string
+  description?: string
+  condition: string
+  fields?: string[]
+}
+
+export interface FieldCondition {
+  condition: string
+}
+
+export interface DeploymentSettings {
+  identity?: IdentitySettings
+}
+
+export interface IdentitySettings {
+  keys?: JWTKey[]
+  issuer?: string
+  subject?: string
+  audience?: string
+  claims?: string[]
+  jwksendpoint?: string
+}
+
+export interface JWTKey {
+  algorithm?: string
+  keyid?: string
+  key?: string
+}

package/src/shared/validation.ts

@@ -0,0 +1,52 @@
+// Copyright (c) 2020,2021,2022, StepZen, Inc.
+
+import * as debug from 'debug'
+import * as fs from 'fs'
+import * as glob from 'glob'
+import * as yaml from 'yaml'
+
+// Validate the Configurationset file
+export const validateConfigurationset = async (file: string | undefined) => {
+  if (!file) {
+    debug('stepzen:sdk')(
+      `validateConfigurationset() expected 'file' to be a` +
+        ` non-empty string but got ${file}`,
+    )
+    throw new Error('You must provide a file path')
+  }
+
+  if (!fs.existsSync(file)) {
+    debug('stepzen:sdk')(`validateConfigurationset() expected ${file} to exist`)
+    throw new Error('The file does not exist')
+  }
+
+  const content = fs.readFileSync(file, 'utf8')
+
+  // Ensure the file is valid YAML
+  try {
+    yaml.parse(content)
+  } catch (error) {
+    debug('stepzen:sdk')(
+      `validateConfigurationset() expected ${file} to parse as YAML,` +
+        ` but got an error ${error}`,
+    )
+    throw new Error('The file is not valid YAML')
+  }
+}
+
+// Validate the Schema directory
+export const validateSchema = async (directory: string | undefined) => {
+  if (!directory) {
+    throw new Error('You must provide a directory path')
+  }
+
+  if (!fs.existsSync(directory)) {
+    throw new Error('The directory does not exist')
+  }
+
+  // Ensure there's a root `index.graphql` file
+  const allSchemaFiles = glob.sync('index.graphql', {cwd: directory})
+  if (allSchemaFiles.length === 0) {
+    throw new Error('Schemas must include an `index.graphql` file')
+  }
+}