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

package/src/commands-v2/account.ts

@@ -0,0 +1,98 @@
+// Copyright (c) 2020,2021,2022, StepZen, Inc.
+
+import {
+  SDKConfigurationV2,
+  StepZenAccountV2,
+  ZenCtlResponseV2,
+} from '../shared/types'
+import {fetchZenCtlGraphQLQuery} from '../shared/graphql-client'
+
+export default async ({
+  account,
+  adminKey,
+  deploymentType,
+  sdkConfig,
+}: {
+  account: string
+  adminKey: string
+  deploymentType: string
+  sdkConfig: SDKConfigurationV2
+}): Promise<ZenCtlResponseV2<StepZenAccountV2>> => {
+  const {data, errors} = await fetchZenCtlGraphQLQuery<{
+    accounts: Array<{
+      deploymentType: string
+      account: string
+      ownerEmail: string
+      adminKey: string
+      apiKeysAsJsonArray: string
+    }>
+  }>({
+    account,
+    adminKey,
+    deploymentType,
+    query: `query (
+      $account: String!
+      $adminKey: String!
+      $deploymentType: String!
+    ) {
+      accounts: account(
+        account: $account
+        adminkey: $adminKey
+        deploymentType: $deploymentType
+      ) {
+        deploymentType: account_deployment_type
+        account: account_name
+        ownerEmail: account_owner_email
+        adminKey: key_value_admin
+        apiKeysAsJsonArray: key_value_api
+      }
+    }`,
+    variables: {
+      account,
+      adminKey,
+      deploymentType,
+    },
+    sdkConfig,
+  })
+
+  if (errors) {
+    // strip graphql-specific error details, leave only the message
+    const message = errors
+      .map(({message}) =>
+        message.startsWith(
+          'ERROR: invalid input value for enum zenctl.deployment_type',
+        )
+          ? `Invalid deployment type: ${deploymentType}`
+          : message,
+      )
+      .join('\n')
+
+    return {
+      data: undefined,
+      error: {
+        message,
+      },
+    }
+  }
+
+  const accounts = data.accounts.filter(Boolean)
+  if (!accounts.length) {
+    return {
+      data: undefined,
+      error: {
+        message: 'Your credentials are invalid',
+      },
+    }
+  }
+
+  return {
+    data: {
+      account: accounts[0].account,
+      deploymentType: accounts[0].deploymentType,
+      ownerEmail: accounts[0].ownerEmail,
+      adminKey: accounts[0].adminKey,
+      apiKeys: JSON.parse(accounts[0].apiKeysAsJsonArray),
+    },
+    error: undefined,
+  }
+}

package/src/commands-v2/deploy.ts

@@ -0,0 +1,145 @@
+// Copyright (c) 2020,2021,2022, StepZen, Inc.
+
+import {
+  Configuration,
+  SchemaFiles,
+  SDKConfigurationV2,
+  StepZenEndpointV2,
+  ZenCtlResponseV2,
+} from '../shared/types'
+import {fetchZenCtlGraphQLQuery} from '../shared/graphql-client'
+
+export default async ({
+  account,
+  deploymentType,
+  folderName,
+  endpointName,
+  public: _public,
+  endpointType,
+  schemaFiles,
+  configuration,
+  adminKey,
+  sdkConfig,
+}: {
+  account: string
+  deploymentType: string
+  folderName: string
+  endpointName: string
+  public: boolean
+  endpointType: string
+  schemaFiles: Readonly<SchemaFiles>
+  configuration: Readonly<Configuration> | null
+  adminKey: string
+  sdkConfig: SDKConfigurationV2
+}): Promise<ZenCtlResponseV2<StepZenEndpointV2>> => {
+  const {data, errors} = await fetchZenCtlGraphQLQuery<{
+    endpoints: Array<{
+      account: string
+      deploymentType: string
+      folderName: string
+      endpointName: string
+      public: boolean
+      endpointType: string
+    }>
+  }>({
+    account,
+    adminKey,
+    deploymentType,
+    query: /* GraphQL */ `
+      mutation (
+        $account: String!
+        $deploymentType: String!
+        $folderName: String!
+        $endpointName: String!
+        $public: Boolean!
+        $endpointType: String!
+        $schemaFiles: SchemaFilesInput!
+        $configuration: Configuration
+        $adminKey: String!
+      ) {
+        endpoints: addEndpoint(
+          account: $account
+          deploymentType: $deploymentType
+          folderName: $folderName
+          endpointName: $endpointName
+          public: $public
+          endpointType: $endpointType
+          schemaFiles: $schemaFiles
+          configuration: $configuration
+          adminkey: $adminKey
+        ) {
+          account: account_name
+          deploymentType: deployment_type
+          folderName: folder_name
+          endpointName: endpoint_name
+          public: endpoint_public
+          endpointType: endpoint_type
+        }
+      }
+    `,
+    variables: {
+      account,
+      deploymentType,
+      folderName,
+      endpointName,
+      public: _public,
+      endpointType,
+      schemaFiles,
+      configuration,
+      adminKey,
+    },
+    sdkConfig,
+  })
+
+  if (errors) {
+    // strip graphql-specific error details, leave only the message
+    const message = errors
+      .map(({message}) => {
+        if (
+          message.startsWith(
+            'ERROR: invalid input value for enum zenctl.deployment_type',
+          )
+        ) {
+          return (
+            `Invalid deployment type: ${deploymentType}.` +
+            ` Please check the 'deploymentType' parameter.`
+          )
+        }
+
+        if (
+          message.startsWith(
+            'ERROR: invalid input value for enum zenctl.endpoint_type',
+          )
+        ) {
+          return (
+            `Invalid endpoint type: ${endpointType}.` +
+            ` Please check the 'endpointType' parameter.`
+          )
+        }
+
+        return message
+      })
+      .join('\n')
+
+    return {
+      data: undefined,
+      error: {
+        message,
+      },
+    }
+  }
+
+  if (!data.endpoints.length) {
+    return {
+      data: undefined,
+      error: {
+        message: 'Invalid credentials',
+      },
+    }
+  }
+
+  return {
+    data: data.endpoints[0],
+    error: undefined,
+  }
+}

package/src/commands-v2/getPublicAccount.ts

@@ -0,0 +1,67 @@
+// Copyright (c) 2020,2021,2022, StepZen, Inc.
+
+import {
+  SDKConfigurationV2,
+  StepZenCredentialsV2,
+  ZenCtlResponseV2,
+} from '../shared/types'
+import {fetchPublicAccountGraphQLQuery} from '../shared/graphql-client'
+
+export default async ({
+  token,
+  deploymentType,
+  sdkConfig,
+}: {
+  token: string
+  deploymentType: string
+  sdkConfig: SDKConfigurationV2
+}): Promise<ZenCtlResponseV2<StepZenCredentialsV2>> => {
+  const url = new URL(sdkConfig.publicAccountApiUrl)
+  // Include 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', token)
+
+  const {data, errors} = await fetchPublicAccountGraphQLQuery<{
+    account: {
+      account: string
+      adminKey: string
+      apiKey: string
+    }
+  }>({
+    url,
+    query: `query (
+      $token: String!
+    ) {
+      account: getAccountDetails(
+        token: $token
+      ) {
+        account: accountName
+        adminKey
+        apiKey
+      }
+    }`,
+    variables: {
+      token,
+    },
+    sdkConfig,
+  })
+
+  if (errors) {
+    // strip graphql-specific error details, leave only the message
+    const message = errors.map(error => error.message).join('\n')
+    return {
+      data: undefined,
+      error: {message},
+    }
+  }
+
+  return {
+    data: {
+      account: data.account.account,
+      adminKey: data.account.adminKey,
+      apiKeys: [data.account.apiKey],
+      deploymentType,
+    },
+    error: undefined,
+  }
+}

package/src/commands-v2/list.ts

@@ -0,0 +1,91 @@
+// Copyright (c) 2020,2021,2022, StepZen, Inc.
+
+import {SDKConfigurationV2, ZenCtlResponseV2} from '../shared/types'
+import {fetchZenCtlGraphQLQuery} from '../shared/graphql-client'
+
+export default async ({
+  account,
+  deploymentType,
+  adminKey,
+  sdkConfig,
+}: {
+  account: string
+  deploymentType: string
+  adminKey: string
+  sdkConfig: SDKConfigurationV2
+}): Promise<
+  ZenCtlResponseV2<
+    Array<{
+      folderName: string
+      endpointName: string
+    }>
+  >
+> => {
+  const {data, errors} = await fetchZenCtlGraphQLQuery<{
+    endpoints: Array<{
+      folderName: string
+      endpointName: string
+    }>
+  }>({
+    account,
+    adminKey,
+    deploymentType,
+    query: /* GraphQL */ `
+      query ($account: String!, $deploymentType: String!, $adminKey: String!) {
+        endpoints: endpointsForAccount(
+          account: $account
+          deploymentType: $deploymentType
+          adminkey: $adminKey
+        ) {
+          endpointName: endpoint_name
+          folderName: folder_name
+        }
+      }
+    `,
+    variables: {
+      account,
+      deploymentType,
+      adminKey,
+    },
+    sdkConfig,
+  })
+
+  if (errors) {
+    // strip graphql-specific error details, leave only the message
+    const message = errors
+      .map(({message}) => {
+        if (
+          message.startsWith(
+            'ERROR: invalid input value for enum zenctl.deployment_type',
+          )
+        ) {
+          return (
+            `Invalid deployment type: ${deploymentType}.` +
+            ` Please check the 'deploymentType' parameter.`
+          )
+        }
+
+        return message
+      })
+      .join('\n')
+
+    return {
+      data: undefined,
+      error: {
+        message,
+      },
+    }
+  }
+
+  // The case with data.endpoints === [] is ambiguous.
+  // It may mean "invalid credentials" and it may mean "no endpoints".
+  // At this point it makes more sense to assume "no endpoints" since
+  // the "invalid credentials" error would be detected earlier, when
+  // creating an SDK client instance.
+  // See https://github.com/steprz/zen/issues/6361
+
+  return {
+    data: data.endpoints,
+    error: undefined,
+  }
+}

package/src/index.ts

@@ -0,0 +1,27 @@
+// Copyright (c) 2020,2021,2022, StepZen, Inc.
+
+import * as path from 'path'
+import {init, SDK} from './init'
+
+export * from './init'
+export * from './init-v2'
+
+/**
+ * The default SDK instance that does not know the name of the app using the SDK.
+ * It tries to guess the app name from `process.argv`
+ *
+ * @deprecated use the init({appName: 'my-app/1.2.3'}) method to initialis an SDK instance
+ */
+const stepzen: SDK = init({
+  // For legacy apps use the script name (e.g. `index.js` as the app name)
+  // Fallback to `node` if this file is imported into an interactive node shell
+  appName: path.basename(process.argv[1] || process.argv[0]),
+})
+
+export default stepzen
+
+// Hack: support both ESM-style imports: `import stepzen from '@stepzen/sdk'`
+// and keep the backwards-compat with CJS-style imports: `const stepzen = require('@stepzen/sdk')`
+// NOTE: if at any point in the future there is a name collision between `stepzen` and ES exports
+// this hack will break
+module.exports = {...module.exports, ...stepzen}

package/src/init-v2.ts

@@ -0,0 +1,44 @@
+// Copyright (c) 2020,2021,2022, StepZen, Inc.
+
+import accountCommand from './commands-v2/account'
+import {createSdkClient} from './client-v2'
+import {getUserAgent} from './shared/request'
+import {SDKConfigurationV2} from './shared/types'
+
+export const initV2 = (sdkConfig: SDKConfigurationV2) => {
+  return {
+    verify: async (
+      account: string,
+      adminkey: string,
+      deploymentType: string,
+    ) => {
+      try {
+        const {data} = await accountCommand({
+          account,
+          adminKey: adminkey,
+          deploymentType,
+          sdkConfig,
+        })
+        return Boolean(data)
+      } catch {
+        return false
+      }
+    },
+    client: async (
+      auth:
+        | {account: string; adminKey: string; deploymentType: string}
+        | {publicAccountToken: string; deploymentType: string},
+    ) => {
+      return createSdkClient(auth, sdkConfig)
+    },
+    get userAgent() {
+      return getUserAgent(sdkConfig)
+    },
+  }
+}
+
+// a helper type to unwrap Promise<U> into U
+type PromisedType<T> = T extends Promise<infer U> ? U : T
+
+export type SDKV2 = ReturnType<typeof initV2>
+export type SDKClientV2 = PromisedType<ReturnType<SDKV2['client']>>

package/src/init.ts

@@ -0,0 +1,45 @@
+// Copyright (c) 2020,2021,2022, StepZen, Inc.
+
+import authenticate from './commands/authenticate'
+import {createSdkClient} from './client'
+import {getUserAgent} from './shared/request'
+import {
+  AnonymousClientOptions,
+  SDKConfiguration,
+  UserCredentialsClientOptions,
+} from './shared/types'
+
+export const init = (sdkConfig: SDKConfiguration) => {
+  const defaults = {
+    domain: process.env.STEPZEN_DOMAIN || 'stepzen.io',
+    server: process.env.STEPZEN_SERVER_URL || 'https://{account}.stepzen.io',
+  }
+
+  return {
+    verify: (account: string, adminkey: string) => {
+      return authenticate(
+        {
+          account,
+          adminkey,
+          server: defaults.server.replace('{account}', account),
+          domain: defaults.domain,
+        },
+        sdkConfig,
+      )
+    },
+    client: async (
+      options: UserCredentialsClientOptions | AnonymousClientOptions,
+    ) => {
+      return createSdkClient({...defaults, ...options}, sdkConfig)
+    },
+    get userAgent() {
+      return getUserAgent(sdkConfig)
+    },
+  }
+}
+
+// a helper type to unwrap Promise<U> into U
+type PromisedType<T> = T extends Promise<infer U> ? U : T
+
+export type SDK = ReturnType<typeof init>
+export type SDKClient = PromisedType<ReturnType<SDK['client']>>

package/src/shared/constants.ts

@@ -0,0 +1,9 @@
+// Copyright (c) 2020,2021,2022, StepZen, Inc.
+
+export const ADMIN_ACCOUNT_URL = '/cli/admin/account'
+export const ADMIN_DEPLOY_URL = '/cli/admin/deploy'
+export const ADMIN_LIST_URL = '/cli/admin/list'
+export const ADMIN_UPLOAD_URL = '/cli/admin/upload'
+export const ADMIN_VERIFY_URL = '/cli/admin/verify'
+
+export const ZENCTL2_URL = '/api/zenctl/__graphql'

package/src/shared/graphql-client.ts

@@ -0,0 +1,136 @@
+// Copyright (c) 2020,2021,2022, StepZen, Inc.
+
+import * as debug from 'debug'
+import fetch from '@stepzen/fetch'
+
+import {SDKConfigurationV2} from './types'
+import {getUserAgent} from './request'
+
+export type GraphQLSuccessResponse<T> = {
+  data: T
+  errors: undefined
+}
+
+export type GraphQLErrorResponse<T> = {
+  data: T | null
+  errors: Array<{
+    message: string
+    locations?: Array<{line: number; column: number}>
+    path?: Array<string | number>
+  }>
+}
+
+export type GraphQLResponse<T> =
+  | GraphQLSuccessResponse<T>
+  | GraphQLErrorResponse<T>
+
+export const fetchGraphQLQuery = async <T>({
+  url,
+  query,
+  variables = {},
+  headers = {},
+}: {
+  url: URL | string
+  query: string
+  variables: Record<string, any>
+  headers: Record<string, any>
+}): Promise<GraphQLResponse<T>> => {
+  debug('stepzen:sdk:url')(url)
+  debug('stepzen:sdk:headers')(headers)
+  debug('stepzen:sdk:query')(query)
+  debug('stepzen:sdk:variables')(variables)
+
+  try {
+    const response = await fetch(url, {
+      method: 'POST',
+      headers: {
+        'content-type': 'application/json',
+        ...headers,
+      },
+      body: JSON.stringify({
+        query,
+        variables,
+      }),
+    })
+
+    if (response.status !== 200) {
+      throw new Error(
+        `Unexpected HTTP status ${response.status}` +
+          ` from the GraphQL endpoint '${url}' (expected 200)`,
+      )
+    }
+
+    const json = await response.json()
+    debug('stepzen:sdk:response')(json)
+
+    const {data, errors} = json
+    if (errors) {
+      return {data, errors}
+    } else if (data) {
+      return {data, errors: undefined}
+    }
+
+    throw new Error(
+      `Unexpected response structure from the GraphQL endpoint '${url}'` +
+        ` (expected {data, errors}, recieved ${JSON.stringify(json)})`,
+    )
+  } catch (error) {
+    debug('stepzen:sdk:response')(`Failed to fetch from a GraphQL API`, error)
+    throw error
+  }
+}
+
+export const fetchZenCtlGraphQLQuery = async <T>({
+  account,
+  adminKey,
+  deploymentType,
+  query,
+  variables = {},
+  sdkConfig,
+}: {
+  account: string
+  adminKey: string
+  deploymentType: string
+  query: string
+  variables: Record<string, any>
+  sdkConfig: SDKConfigurationV2
+}): Promise<GraphQLResponse<T>> => {
+  try {
+    return await fetchGraphQLQuery({
+      url: sdkConfig.zenctlApiUrl,
+      query,
+      variables,
+      headers: {
+        'user-agent': getUserAgent(sdkConfig),
+        host: `stepzen.${deploymentType}.net`,
+      },
+    })
+  } catch (error) {
+    throw new Error(`Failed to connect to ZenCtl API. ${error}`)
+  }
+}
+
+export const fetchPublicAccountGraphQLQuery = async <T>({
+  url,
+  query,
+  variables = {},
+  sdkConfig,
+}: {
+  url: URL | string
+  query: string
+  variables: Record<string, any>
+  sdkConfig: SDKConfigurationV2
+}): Promise<GraphQLResponse<T>> => {
+  try {
+    return await fetchGraphQLQuery({
+      url,
+      query,
+      variables,
+      headers: {
+        'user-agent': getUserAgent(sdkConfig),
+      },
+    })
+  } catch (error) {
+    throw new Error(`Failed to connect to Public Account API. ${error}`)
+  }
+}