@api-client/core 0.19.24 → 0.19.26

package/src/models/store/Deployment.ts

@@ -1,5 +1,8 @@
 import type { FieldValidationMessage } from '../../exceptions/validation_error.js'
 import { nanoid } from '../../nanoid.js'
+import { DeploymentKind } from '../kinds.js'
+
+export { DeploymentKind }
 
 /**
  * Status of the deployment
@@ -23,11 +26,21 @@ export enum DeploymentStatus {
   Failed = 3,
 }
 
+/**
+ * Environment tag for logical deployment grouping
+ */
+export enum DeploymentEnvironment {
+  PROD = 'prod',
+  STAGING = 'staging',
+  DEV = 'dev',
+}
+
 export interface DeploymentSchema {
+  kind: typeof DeploymentKind
   /**
    * Primary key (nanoid)
    */
-  id: string
+  key: string
   /**
    * ID of the organization
    */
@@ -37,25 +50,31 @@ export interface DeploymentSchema {
    */
   apiId: string
   /**
-   * The version of the deployment (e.g., 'v1', 'v2')
+   * Denormalized organization slug
    */
-  deploymentVersion: string
+  orgSlug: string
   /**
-   * The semantic version of the deployed API model (e.g., '1.0.1')
+   * Denormalized API slug
    */
-  apiModelVersion: string
+  apiSlug: string
   /**
-   * Status of the deployment
+   * Environment tag
    */
-  status: DeploymentStatus
+  env: DeploymentEnvironment
   /**
-   * Optional custom path for staging (e.g., '/dev')
+   * The version of the deployment (e.g., 'v1', 'v2')
+   * It must be set for production environments.
+   * It cannot be set for non-production environments (e.g. 'dev').
    */
-  stagingPath?: string
+  version?: string
   /**
-   * Reference to the optimized model in MongoDB
+   * The semantic version of the deployed API model (e.g., '1.0.1').
    */
-  mongoModelId?: string
+  modelVersion: string
+  /**
+   * Status of the deployment
+   */
+  status: DeploymentStatus
   /**
    * Timestamp of creation
    */
@@ -64,79 +83,110 @@ export interface DeploymentSchema {
    * Timestamp of last update
    */
   updatedAt: number
+  /**
+   * The base URI to the API.
+   * Note: This field is computed at runtime when the deployment status is active.
+   * Note: This field is ignored when creating or updating a deployment.
+   */
+  baseUri?: string
+  /**
+   * The URI to the API portal.
+   * Note: This field is computed at runtime when the deployment status is active.
+   * Note: This field is ignored when creating or updating a deployment.
+   */
+  portalUri?: string
 }
 
 export class Deployment implements DeploymentSchema {
-  id: string
+  readonly kind: typeof DeploymentKind = DeploymentKind
+  key: string
   orgId: string
   apiId: string
-  deploymentVersion: string
-  apiModelVersion: string
+  orgSlug: string
+  apiSlug: string
+  env: DeploymentEnvironment
+  version?: string
+  modelVersion: string
   status: DeploymentStatus
-  stagingPath?: string
-  mongoModelId?: string
   createdAt: number
   updatedAt: number
+  baseUri?: string
+  portalUri?: string
 
   static createSchema(input: Partial<DeploymentSchema> = {}): DeploymentSchema {
-    const id = input.id ?? nanoid()
+    const key = input.key ?? nanoid()
     const result: DeploymentSchema = {
-      id,
+      kind: DeploymentKind,
+      key,
       orgId: input.orgId || '',
       apiId: input.apiId || '',
-      deploymentVersion: input.deploymentVersion || 'v0',
-      apiModelVersion: input.apiModelVersion || '0.0.0',
+      orgSlug: input.orgSlug || '',
+      apiSlug: input.apiSlug || '',
+      env: input.env ?? DeploymentEnvironment.DEV,
+      modelVersion: input.modelVersion || '0.0.0',
       status: input.status ?? DeploymentStatus.Pending,
       createdAt: input.createdAt ?? Date.now(),
       updatedAt: input.updatedAt ?? Date.now(),
     }
-    if (input.stagingPath) {
-      result.stagingPath = input.stagingPath
+    if (input.baseUri) {
+      result.baseUri = input.baseUri
     }
-    if (input.mongoModelId) {
-      result.mongoModelId = input.mongoModelId
+    if (input.portalUri) {
+      result.portalUri = input.portalUri
+    }
+    if (input.version) {
+      result.version = input.version
     }
     return result
   }
 
   constructor(state?: Partial<DeploymentSchema>) {
     const init = Deployment.createSchema(state)
-    this.id = init.id
+    this.key = init.key
     this.orgId = init.orgId
     this.apiId = init.apiId
-    this.deploymentVersion = init.deploymentVersion
-    this.apiModelVersion = init.apiModelVersion
+    this.orgSlug = init.orgSlug
+    this.apiSlug = init.apiSlug
+    this.env = init.env
+    this.version = init.version
     this.status = init.status
-    if (init.stagingPath) {
-      this.stagingPath = init.stagingPath
-    }
-    if (init.mongoModelId) {
-      this.mongoModelId = init.mongoModelId
-    }
     this.createdAt = init.createdAt
     this.updatedAt = init.updatedAt
+    this.modelVersion = init.modelVersion
+    this.baseUri = init.baseUri
+    this.portalUri = init.portalUri
   }
 
   toJSON(): DeploymentSchema {
     const result: DeploymentSchema = {
-      id: this.id,
+      kind: DeploymentKind,
+      key: this.key,
       orgId: this.orgId,
       apiId: this.apiId,
-      deploymentVersion: this.deploymentVersion,
-      apiModelVersion: this.apiModelVersion,
+      orgSlug: this.orgSlug,
+      apiSlug: this.apiSlug,
+      env: this.env,
+      modelVersion: this.modelVersion,
       status: this.status,
       createdAt: this.createdAt,
       updatedAt: this.updatedAt,
     }
-    if (this.stagingPath) {
-      result.stagingPath = this.stagingPath
+    if (this.version) {
+      result.version = this.version
+    }
+    if (this.baseUri) {
+      result.baseUri = this.baseUri
     }
-    if (this.mongoModelId) {
-      result.mongoModelId = this.mongoModelId
+    if (this.portalUri) {
+      result.portalUri = this.portalUri
     }
     return result
   }
 
+  /**
+   * Validates the deployment.
+   * @returns An array of validation messages.
+   */
   validate(): FieldValidationMessage[] {
     const result: FieldValidationMessage[] = []
 
@@ -154,20 +204,47 @@ export class Deployment implements DeploymentSchema {
         rule: 'notEmpty',
       })
     }
-    if (this.deploymentVersion === '') {
+    if (this.orgSlug === '') {
+      result.push({
+        field: 'orgSlug',
+        message: 'Org slug must not be empty',
+        rule: 'notEmpty',
+      })
+    }
+    if (this.apiSlug === '') {
       result.push({
-        field: 'deploymentVersion',
-        message: 'Deployment version must not be empty',
+        field: 'apiSlug',
+        message: 'API slug must not be empty',
         rule: 'notEmpty',
       })
     }
-    if (this.apiModelVersion === '') {
+    if (!this.env) {
       result.push({
-        field: 'apiModelVersion',
+        field: 'env',
+        message: 'Environment tag must not be empty',
+        rule: 'notEmpty',
+      })
+    }
+    if (this.modelVersion === '') {
+      result.push({
+        field: 'modelVersion',
         message: 'API model version must not be empty',
         rule: 'notEmpty',
       })
     }
+    if (this.env === DeploymentEnvironment.PROD && !this.version) {
+      result.push({
+        field: 'version',
+        message: 'Version must not be empty for production environment',
+        rule: 'notEmpty',
+      })
+    } else if (this.env !== DeploymentEnvironment.PROD && this.version) {
+      result.push({
+        field: 'version',
+        message: 'Version must not be present for non-production environment',
+        rule: 'notEmpty',
+      })
+    }
     return result
   }
 }

package/src/sdk/DataCatalogSdk.ts

@@ -1,11 +1,4 @@
-import {
-  SdkBase,
-  E_RESPONSE_STATUS,
-  E_RESPONSE_NO_VALUE,
-  E_INVALID_JSON,
-  E_RESPONSE_UNKNOWN,
-  SdkOptions,
-} from './SdkBase.js'
+import { SdkBase, E_RESPONSE_STATUS, SdkOptions } from './SdkBase.js'
 import { ContextListResult, ContextListOptions, ContextChangeRecord } from '../events/BaseEvents.js'
 import type {
   DataCatalogSchema,
@@ -19,7 +12,6 @@ import { DataCatalogKind, DataCatalogVersionKind } from '../models/kinds.js'
 import type { DataCatalogVersionSchema } from '../models/DataCatalogVersion.js'
 import type { ForeignDomainDependency } from '../modeling/types.js'
 import type { DataDomainSchema } from '../modeling/DataDomain.js'
-import { Exception } from '../exceptions/exception.js'
 
 export interface DataCatalogListOptions extends ContextListOptions {
   scope?: DataCatalogScope
@@ -38,26 +30,7 @@ export class DataCatalogSdk extends SdkBase {
       url.searchParams.set('scope', opts.scope)
     }
     const result = await this.sdk.http.get(url.toString(), { token })
-    this.inspectCommonStatusCodes(result)
-    const E_PREFIX = 'Unable to list data domains. '
-    if (result.status !== 200) {
-      this.logInvalidResponse(result)
-      throw this.createApiError(`${E_PREFIX}${E_RESPONSE_STATUS}${result.status}`, result.body)
-    }
-    if (!result.body) {
-      throw new Exception(`${E_PREFIX}${E_RESPONSE_NO_VALUE}`, { code: 'E_RESPONSE_NO_VALUE', status: result.status })
-    }
-
-    let data: ContextListResult<DataCatalogSchemaWithVersion>
-    try {
-      data = JSON.parse(result.body)
-    } catch {
-      throw new Exception(`${E_PREFIX}${E_INVALID_JSON}`, { code: 'E_INVALID_JSON', status: result.status })
-    }
-    if (!Array.isArray(data.items)) {
-      throw new Exception(`${E_PREFIX}${E_RESPONSE_UNKNOWN}`, { code: 'E_RESPONSE_UNKNOWN', status: result.status })
-    }
-    return data
+    return this.processListResponse<DataCatalogSchemaWithVersion>(result, 'Unable to list data domains. ')
   }
 
   /**
@@ -68,25 +41,7 @@ export class DataCatalogSdk extends SdkBase {
     const { token } = request
     const url = this.sdk.getUrl(RouteBuilder.dataCatalogEntryVersions(key))
     const result = await this.sdk.http.get(url.toString(), { token })
-    this.inspectCommonStatusCodes(result)
-    const E_PREFIX = 'Unable to list data domain versions. '
-    if (result.status !== 200) {
-      this.logInvalidResponse(result)
-      throw this.createApiError(`${E_PREFIX}${E_RESPONSE_STATUS}${result.status}`, result.body)
-    }
-    if (!result.body) {
-      throw new Exception(`${E_PREFIX}${E_RESPONSE_NO_VALUE}`, { code: 'E_RESPONSE_NO_VALUE', status: result.status })
-    }
-    let data: ContextListResult<DataCatalogVersionInfo>
-    try {
-      data = JSON.parse(result.body)
-    } catch {
-      throw new Exception(`${E_PREFIX}${E_INVALID_JSON}`, { code: 'E_INVALID_JSON', status: result.status })
-    }
-    if (!Array.isArray(data.items)) {
-      throw new Exception(`${E_PREFIX}${E_RESPONSE_UNKNOWN}`, { code: 'E_RESPONSE_UNKNOWN', status: result.status })
-    }
-    return data
+    return this.processListResponse<DataCatalogVersionInfo>(result, 'Unable to list data domain versions. ')
   }
 
   /**
@@ -112,19 +67,8 @@ export class DataCatalogSdk extends SdkBase {
       this.logInvalidResponse(result)
       throw this.createApiError(`${E_PREFIX}${E_RESPONSE_STATUS}${result.status}`, result.body)
     }
-
-    if (!result.body) {
-      throw new Exception(`${E_PREFIX}${E_RESPONSE_NO_VALUE}`, { code: 'E_RESPONSE_NO_VALUE', status: result.status })
-    }
-    let data: ContextChangeRecord<DataCatalogSchema>
-    try {
-      data = JSON.parse(result.body)
-    } catch {
-      throw new Exception(`${E_PREFIX}${E_INVALID_JSON}`, { code: 'E_INVALID_JSON', status: result.status })
-    }
-    if (!data.key) {
-      throw new Exception(`${E_PREFIX}${E_RESPONSE_UNKNOWN}`, { code: 'E_RESPONSE_UNKNOWN', status: result.status })
-    }
+    const data = this.readResponseJSON<DataCatalogSchema>(result, E_PREFIX)
+    this.assertObjectKind(E_PREFIX, DataCatalogKind, data.kind)
     return data
   }
 
@@ -138,18 +82,8 @@ export class DataCatalogSdk extends SdkBase {
       this.logInvalidResponse(result)
       throw this.createApiError(`${E_PREFIX}${E_RESPONSE_STATUS}${result.status}`, result.body)
     }
-    if (!result.body) {
-      throw new Exception(`${E_PREFIX}${E_RESPONSE_NO_VALUE}`, { code: 'E_RESPONSE_NO_VALUE', status: result.status })
-    }
-    let data: DataCatalogSchema
-    try {
-      data = JSON.parse(result.body)
-    } catch {
-      throw new Exception(`${E_PREFIX}${E_INVALID_JSON}`, { code: 'E_INVALID_JSON', status: result.status })
-    }
-    if (data.kind !== DataCatalogKind) {
-      throw new Exception(`${E_PREFIX}${E_RESPONSE_UNKNOWN}`, { code: 'E_RESPONSE_UNKNOWN', status: result.status })
-    }
+    const data = this.readResponseJSON<DataCatalogSchema>(result, E_PREFIX)
+    this.assertObjectKind(E_PREFIX, DataCatalogKind, data.kind)
     return data
   }
 
@@ -180,18 +114,8 @@ export class DataCatalogSdk extends SdkBase {
       this.logInvalidResponse(result)
       throw this.createApiError(`${E_PREFIX}${E_RESPONSE_STATUS}${result.status}`, result.body)
     }
-    if (!result.body) {
-      throw new Exception(`${E_PREFIX}${E_RESPONSE_NO_VALUE}`, { code: 'E_RESPONSE_NO_VALUE', status: result.status })
-    }
-    let data: ContextChangeRecord<DataCatalogSchema>
-    try {
-      data = JSON.parse(result.body)
-    } catch {
-      throw new Exception(`${E_PREFIX}${E_INVALID_JSON}`, { code: 'E_INVALID_JSON', status: result.status })
-    }
-    if (data.kind !== DataCatalogKind) {
-      throw new Exception(`${E_PREFIX}${E_RESPONSE_UNKNOWN}`, { code: 'E_RESPONSE_UNKNOWN', status: result.status })
-    }
+    const data = this.readResponseJSON<DataCatalogSchema>(result, E_PREFIX)
+    this.assertObjectKind(E_PREFIX, DataCatalogKind, data.kind)
     return data
   }
 
@@ -211,18 +135,8 @@ export class DataCatalogSdk extends SdkBase {
       this.logInvalidResponse(result)
       throw this.createApiError(`${E_PREFIX}${E_RESPONSE_STATUS}${result.status}`, result.body)
     }
-    if (!result.body) {
-      throw new Exception(`${E_PREFIX}${E_RESPONSE_NO_VALUE}`, { code: 'E_RESPONSE_NO_VALUE', status: result.status })
-    }
-    let data: ContextChangeRecord<DataCatalogSchema>
-    try {
-      data = JSON.parse(result.body)
-    } catch {
-      throw new Exception(`${E_PREFIX}${E_INVALID_JSON}`, { code: 'E_INVALID_JSON', status: result.status })
-    }
-    if (data.kind !== DataCatalogKind) {
-      throw new Exception(`${E_PREFIX}${E_RESPONSE_UNKNOWN}`, { code: 'E_RESPONSE_UNKNOWN', status: result.status })
-    }
+    const data = this.readResponseJSON<DataCatalogSchema>(result, E_PREFIX)
+    this.assertObjectKind(E_PREFIX, DataCatalogKind, data.kind)
     return data
   }
 
@@ -247,18 +161,8 @@ export class DataCatalogSdk extends SdkBase {
       this.logInvalidResponse(result)
       throw this.createApiError(`${E_PREFIX}${E_RESPONSE_STATUS}${result.status}`, result.body)
     }
-    if (!result.body) {
-      throw new Exception(`${E_PREFIX}${E_RESPONSE_NO_VALUE}`, { code: 'E_RESPONSE_NO_VALUE', status: result.status })
-    }
-    let data: ContextChangeRecord<DataCatalogVersionSchema>
-    try {
-      data = JSON.parse(result.body)
-    } catch {
-      throw new Exception(`${E_PREFIX}${E_INVALID_JSON}`, { code: 'E_INVALID_JSON', status: result.status })
-    }
-    if (data.kind !== DataCatalogVersionKind) {
-      throw new Exception(`${E_PREFIX}${E_RESPONSE_UNKNOWN}`, { code: 'E_RESPONSE_UNKNOWN', status: result.status })
-    }
+    const data = this.readResponseJSON<DataCatalogVersionSchema>(result, E_PREFIX)
+    this.assertObjectKind(E_PREFIX, DataCatalogVersionKind, data.kind)
     return data
   }
 
@@ -272,18 +176,8 @@ export class DataCatalogSdk extends SdkBase {
       this.logInvalidResponse(result)
       throw this.createApiError(`${E_PREFIX}${E_RESPONSE_STATUS}${result.status}`, result.body)
     }
-    if (!result.body) {
-      throw new Exception(`${E_PREFIX}${E_RESPONSE_NO_VALUE}`, { code: 'E_RESPONSE_NO_VALUE', status: result.status })
-    }
-    let data: DataCatalogVersionSchema
-    try {
-      data = JSON.parse(result.body)
-    } catch {
-      throw new Exception(`${E_PREFIX}${E_INVALID_JSON}`, { code: 'E_INVALID_JSON', status: result.status })
-    }
-    if (data.kind !== DataCatalogVersionKind) {
-      throw new Exception(`${E_PREFIX}${E_RESPONSE_UNKNOWN}`, { code: 'E_RESPONSE_UNKNOWN', status: result.status })
-    }
+    const data = this.readResponseJSON<DataCatalogVersionSchema>(result, E_PREFIX)
+    this.assertObjectKind(E_PREFIX, DataCatalogVersionKind, data.kind)
     return data
   }
 
@@ -301,25 +195,7 @@ export class DataCatalogSdk extends SdkBase {
         'content-type': 'application/json',
       },
     })
-    this.inspectCommonStatusCodes(result)
-    const E_PREFIX = 'Unable to list data domain dependencies. '
-    if (result.status !== 200) {
-      this.logInvalidResponse(result)
-      throw this.createApiError(`${E_PREFIX}${E_RESPONSE_STATUS}${result.status}`, result.body)
-    }
-    if (!result.body) {
-      throw new Exception(`${E_PREFIX}${E_RESPONSE_NO_VALUE}`, { code: 'E_RESPONSE_NO_VALUE', status: result.status })
-    }
-    let data: ContextListResult<DataDomainSchema>
-    try {
-      data = JSON.parse(result.body)
-    } catch {
-      throw new Exception(`${E_PREFIX}${E_INVALID_JSON}`, { code: 'E_INVALID_JSON', status: result.status })
-    }
-    if (!Array.isArray(data.items)) {
-      throw new Exception(`${E_PREFIX}${E_RESPONSE_UNKNOWN}`, { code: 'E_RESPONSE_UNKNOWN', status: result.status })
-    }
-    return data
+    return this.processListResponse<DataDomainSchema>(result, 'Unable to list data domain dependencies. ')
   }
 
   async deprecateVersion(
@@ -344,18 +220,8 @@ export class DataCatalogSdk extends SdkBase {
       this.logInvalidResponse(result)
       throw this.createApiError(`${E_PREFIX}${E_RESPONSE_STATUS}${result.status}`, result.body)
     }
-    if (!result.body) {
-      throw new Exception(`${E_PREFIX}${E_RESPONSE_NO_VALUE}`, { code: 'E_RESPONSE_NO_VALUE', status: result.status })
-    }
-    let data: ContextChangeRecord<DataCatalogVersionSchema>
-    try {
-      data = JSON.parse(result.body)
-    } catch {
-      throw new Exception(`${E_PREFIX}${E_INVALID_JSON}`, { code: 'E_INVALID_JSON', status: result.status })
-    }
-    if (data.kind !== DataCatalogVersionKind) {
-      throw new Exception(`${E_PREFIX}${E_RESPONSE_UNKNOWN}`, { code: 'E_RESPONSE_UNKNOWN', status: result.status })
-    }
+    const data = this.readResponseJSON<DataCatalogVersionSchema>(result, E_PREFIX)
+    this.assertObjectKind(E_PREFIX, DataCatalogVersionKind, data.kind)
     return data
   }
 
@@ -373,18 +239,8 @@ export class DataCatalogSdk extends SdkBase {
       this.logInvalidResponse(result)
       throw this.createApiError(`${E_PREFIX}${E_RESPONSE_STATUS}${result.status}`, result.body)
     }
-    if (!result.body) {
-      throw new Exception(`${E_PREFIX}${E_RESPONSE_NO_VALUE}`, { code: 'E_RESPONSE_NO_VALUE', status: result.status })
-    }
-    let data: ContextChangeRecord<DataCatalogVersionSchema>
-    try {
-      data = JSON.parse(result.body)
-    } catch {
-      throw new Exception(`${E_PREFIX}${E_INVALID_JSON}`, { code: 'E_INVALID_JSON', status: result.status })
-    }
-    if (data.kind !== DataCatalogVersionKind) {
-      throw new Exception(`${E_PREFIX}${E_RESPONSE_UNKNOWN}`, { code: 'E_RESPONSE_UNKNOWN', status: result.status })
-    }
+    const data = this.readResponseJSON<DataCatalogVersionSchema>(result, E_PREFIX)
+    this.assertObjectKind(E_PREFIX, DataCatalogVersionKind, data.kind)
     return data
   }
 
@@ -408,18 +264,8 @@ export class DataCatalogSdk extends SdkBase {
       this.logInvalidResponse(result)
       throw this.createApiError(`${E_PREFIX}${E_RESPONSE_STATUS}${result.status}`, result.body)
     }
-    if (!result.body) {
-      throw new Exception(`${E_PREFIX}${E_RESPONSE_NO_VALUE}`, { code: 'E_RESPONSE_NO_VALUE', status: result.status })
-    }
-    let data: DataCatalogStatus
-    try {
-      data = JSON.parse(result.body)
-    } catch {
-      throw new Exception(`${E_PREFIX}${E_INVALID_JSON}`, { code: 'E_INVALID_JSON', status: result.status })
-    }
-    if (data.kind !== DataCatalogKind) {
-      throw new Exception(`${E_PREFIX}${E_RESPONSE_UNKNOWN}`, { code: 'E_RESPONSE_UNKNOWN', status: result.status })
-    }
+    const data = this.readResponseJSON<DataCatalogStatus>(result, E_PREFIX)
+    this.assertObjectKind(E_PREFIX, DataCatalogKind, data.kind)
     return data
   }
 }

package/src/sdk/DeploymentsSdk.ts

@@ -0,0 +1,123 @@
+import { SdkBase, type SdkOptions, E_RESPONSE_STATUS } from './SdkBase.js'
+import { RouteBuilder } from './RouteBuilder.js'
+import { DeploymentEnvironment, DeploymentKind, DeploymentSchema } from '../models/store/Deployment.js'
+import { Exception } from '../exceptions/exception.js'
+import type { ContextListOptions, ContextListResult } from '../events/BaseEvents.js'
+
+export interface CreateDeploymentPayload {
+  /**
+   * API file ID
+   */
+  fid: string
+  /**
+   * API deployment version (e.g. "v1", "v2")
+   * It is optional for non production environments (e.g. 'dev').
+   */
+  version?: string
+  /**
+   * API model version (e.g. "3.1.2", "4.0.0")
+   */
+  modelVersion: string
+  /**
+   * Target environment tag (e.g. "prod", "staging", "dev")
+   */
+  env: DeploymentEnvironment
+}
+
+export class DeploymentsSdk extends SdkBase {
+  async list(
+    oid: string,
+    options: ContextListOptions = {},
+    request: SdkOptions = {}
+  ): Promise<ContextListResult<DeploymentSchema>> {
+    const { token = this.sdk.token } = request
+    const url = this.sdk.getUrl(RouteBuilder.deployments(oid))
+    this.sdk.appendListOptions(url, options)
+    const result = await this.sdk.http.get(url.toString(), { token })
+    return this.processListResponse<DeploymentSchema>(result, 'Unable to list deployments. ')
+  }
+
+  /**
+   * Triggers the creation of a new deployment.
+   *
+   * @param oid The parent organization key
+   * @param payload The deployment payload
+   * @param request Optional SDK options
+   */
+  async create(oid: string, payload: CreateDeploymentPayload, request: SdkOptions = {}): Promise<DeploymentSchema> {
+    // Let's do some basic validation before hitting the API endpoint.
+    if (payload.env === DeploymentEnvironment.PROD && !payload.version) {
+      throw new Exception(`Version must not be empty for production environment: ${payload.env}`, {
+        code: 'INVALID_DEPLOYMENT_VERSION',
+        help: 'Please provide a version for production environment',
+        status: 400,
+      })
+    } else if (payload.env !== DeploymentEnvironment.PROD && payload.version) {
+      throw new Exception(`Version must not be present for non-production environment: ${payload.env}`, {
+        code: 'INVALID_DEPLOYMENT_VERSION',
+        help: 'Please remove the version for non-production environment',
+        status: 400,
+      })
+    }
+    const url = this.sdk.getUrl(RouteBuilder.deployments(oid))
+    const { token = this.sdk.token } = request
+    const result = await this.sdk.http.post(url.toString(), {
+      token,
+      body: JSON.stringify(payload),
+      headers: {
+        'content-type': 'application/json',
+      },
+    })
+
+    this.inspectCommonStatusCodes(result)
+    const E_PREFIX = 'Unable to create a deployment. '
+    // It is accepted for async processing.
+    if (result.status !== 202) {
+      this.logInvalidResponse(result)
+      throw this.createApiError(`${E_PREFIX}${E_RESPONSE_STATUS}${result.status}`, result.body)
+    }
+    const data = this.readResponseJSON<DeploymentSchema>(result, E_PREFIX)
+    this.assertObjectKind(E_PREFIX, DeploymentKind, data.kind)
+    return data
+  }
+
+  /**
+   * Reads the status of an API deployment.
+   *
+   * @param oid The parent organization key
+   * @param did The deployment ID
+   * @param request Optional SDK options
+   */
+  async read(oid: string, did: string, request: SdkOptions = {}): Promise<DeploymentSchema> {
+    const url = this.sdk.getUrl(RouteBuilder.deployment(oid, did))
+    const { token = this.sdk.token } = request
+    const result = await this.sdk.http.get(url.toString(), { token })
+
+    this.inspectCommonStatusCodes(result)
+    const E_PREFIX = 'Unable to read a deployment. '
+    if (result.status !== 200) {
+      this.logInvalidResponse(result)
+      throw this.createApiError(`${E_PREFIX}${E_RESPONSE_STATUS}${result.status}`, result.body)
+    }
+    const data = this.readResponseJSON<DeploymentSchema>(result, E_PREFIX)
+    this.assertObjectKind(E_PREFIX, DeploymentKind, data.kind)
+    return data
+  }
+
+  /**
+   * Deactivates a deployment. Essentially it disables the version of an API.
+   * @param oid The organization ID
+   * @param did The deployment ID
+   */
+  async deactivate(oid: string, did: string, request: SdkOptions = {}): Promise<void> {
+    const url = this.sdk.getUrl(RouteBuilder.deployment(oid, did))
+    const { token = this.sdk.token } = request
+    const result = await this.sdk.http.delete(url.toString(), { token })
+    this.inspectCommonStatusCodes(result)
+    const E_PREFIX = 'Unable to deactivate a deployment. '
+    if (result.status !== 204) {
+      this.logInvalidResponse(result)
+      throw this.createApiError(`${E_PREFIX}${E_RESPONSE_STATUS}${result.status}`, result.body)
+    }
+  }
+}

package/src/sdk/RouteBuilder.ts

@@ -334,4 +334,12 @@ export class RouteBuilder {
   static orgSlugValidate(): string {
     return `/v1/orgs/slugs/validate`
   }
+
+  static deployments(oid: string): string {
+    return `/v1/orgs/${oid}/deployments`
+  }
+
+  static deployment(oid: string, deploymentId: string): string {
+    return `${RouteBuilder.deployments(oid)}/${deploymentId}`
+  }
 }