feat(template): add template getMany and get methods [DX-898] [DX-899]

lib/adapters/REST/endpoints/index.ts

@@ -69,6 +69,7 @@ import * as Task from './task'
 import * as Team from './team'
 import * as TeamMembership from './team-membership'
 import * as TeamSpaceMembership from './team-space-membership'
+import * as Template from './template'
 import * as UIConfig from './ui-config'
 import * as Upload from './upload'
 import * as View from './view'
@@ -153,6 +154,7 @@ export default {
   Team,
   TeamMembership,
   TeamSpaceMembership,
+  Template,
   UIConfig,
   Upload,
   UploadCredential,

lib/adapters/REST/endpoints/template.ts

@@ -0,0 +1,32 @@
+import type { RawAxiosRequestHeaders } from 'axios'
+import type { AxiosInstance } from 'contentful-sdk-core'
+import type {
+  CursorPaginatedCollectionProp,
+  GetSpaceEnvironmentParams,
+  GetTemplateParams,
+} from '../../../common-types'
+import type { TemplateProps, TemplateQueryOptions } from '../../../entities/template'
+import type { RestEndpoint } from '../types'
+import * as raw from './raw'
+
+const getBaseUrl = (params: GetSpaceEnvironmentParams) =>
+  `/spaces/${params.spaceId}/environments/${params.environmentId}/templates`
+
+export const getMany: RestEndpoint<'Template', 'getMany'> = (
+  http: AxiosInstance,
+  params: GetSpaceEnvironmentParams & { query: TemplateQueryOptions },
+  headers?: RawAxiosRequestHeaders,
+) => {
+  return raw.get<CursorPaginatedCollectionProp<TemplateProps>>(http, getBaseUrl(params), {
+    params: params.query,
+    headers,
+  })
+}
+
+export const get: RestEndpoint<'Template', 'get'> = (
+  http: AxiosInstance,
+  params: GetTemplateParams,
+  headers?: RawAxiosRequestHeaders,
+) => {
+  return raw.get<TemplateProps>(http, getBaseUrl(params) + `/${params.templateId}`, { headers })
+}

lib/common-types.ts

@@ -66,6 +66,7 @@
   CreateComponentTypeProps,
   UpdateComponentTypeProps,
 } from './entities/component-type'
+import type { TemplateProps, TemplateQueryOptions } from './entities/template'
 import type {
   CreateViewProps,
   UpdateViewProps,
@@ -302,7 +303,7 @@
   select?: string
   links_to_entry?: string
 
   [key: string]: any
 }
 
 /** @internal */
@@ -932,6 +933,9 @@
   (opts: MROpts<'TeamSpaceMembership', 'update', UA>): MRReturn<'TeamSpaceMembership', 'update'>
   (opts: MROpts<'TeamSpaceMembership', 'delete', UA>): MRReturn<'TeamSpaceMembership', 'delete'>
 
+  (opts: MROpts<'Template', 'getMany', UA>): MRReturn<'Template', 'getMany'>
+  (opts: MROpts<'Template', 'get', UA>): MRReturn<'Template', 'get'>
+
   (opts: MROpts<'UIConfig', 'get', UA>): MRReturn<'UIConfig', 'get'>
   (opts: MROpts<'UIConfig', 'update', UA>): MRReturn<'UIConfig', 'update'>
 
@@ -2612,6 +2616,16 @@
     }
     delete: { params: GetTeamSpaceMembershipParams; return: any }
   }
+  Template: {
+    getMany: {
+      params: GetSpaceEnvironmentParams & { query: TemplateQueryOptions }
+      return: CursorPaginatedCollectionProp<TemplateProps>
+    }
+    get: {
+      params: GetTemplateParams
+      return: TemplateProps
+    }
+  }
   UIConfig: {
     get: { params: GetUIConfigParams; return: UIConfigProps }
     update: { params: GetUIConfigParams; payload: UIConfigProps; return: UIConfigProps }

lib/plain/entities/template.ts

@@ -0,0 +1,47 @@
+import type {
+  CursorPaginatedCollectionProp,
+  GetSpaceEnvironmentParams,
+  GetTemplateParams,
+} from '../../common-types'
+import type { TemplateProps, TemplateQueryOptions } from '../../entities/template'
+import type { OptionalDefaults } from '../wrappers/wrap'
+
+export type TemplatePlainClientAPI = {
+  /**
+   * Fetches all templates for a space and environment
+   * @param params the space, environment IDs and query options (see {@link TemplateQueryOptions})
+   * @returns a collection of templates
+   * @throws if the request fails, or the space or environment is not found
+   * @internal - Experimental endpoint, subject to breaking changes without notice
+   * @example
+   * ```javascript
+   * const templates = await client.template.getMany({
+   *   spaceId: '<space_id>',
+   *   environmentId: '<environment_id>',
+   *   query: {
+   *     limit: 10,
+   *   },
+   * });
+   * ```
+   */
+  getMany(
+    params: OptionalDefaults<GetSpaceEnvironmentParams & { query: TemplateQueryOptions }>,
+  ): Promise<CursorPaginatedCollectionProp<TemplateProps>>
+
+  /**
+   * Fetches a single template by ID
+   * @param params the space, environment, and template IDs
+   * @returns the template
+   * @throws if the request fails, or the space, environment, or template is not found
+   * @internal - Experimental endpoint, subject to breaking changes without notice
+   * @example
+   * ```javascript
+   * const template = await client.template.get({
+   *   spaceId: '<space_id>',
+   *   environmentId: '<environment_id>',
+   *   templateId: '<template_id>',
+   * });
+   * ```
+   */
+  get(params: OptionalDefaults<GetTemplateParams>): Promise<TemplateProps>
+}

lib/plain/plain-client-types.ts

@@ -125,6 +125,7 @@ import type { TaskPlainClientAPI } from './entities/task'
 import type { TeamPlainClientAPI } from './entities/team'
 import type { TeamMembershipPlainClientAPI } from './entities/team-membership'
 import type { TeamSpaceMembershipPlainClientAPI } from './entities/team-space-membership'
+import type { TemplatePlainClientAPI } from './entities/template'
 import type { UIConfigPlainClientAPI } from './entities/ui-config'
 import type { UploadPlainClientAPI } from './entities/upload'
 import type { UploadCredentialAPI } from './entities/upload-credential'
@@ -729,6 +730,7 @@ export type PlainClientAPI = {
   team: TeamPlainClientAPI
   teamMembership: TeamMembershipPlainClientAPI
   teamSpaceMembership: TeamSpaceMembershipPlainClientAPI
+  template: TemplatePlainClientAPI
   uiConfig: UIConfigPlainClientAPI
   userUIConfig: UserUIConfigPlainClientAPI
   workflowDefinition: WorkflowDefinitionPlainClientAPI

lib/plain/plain-client.ts

@@ -627,6 +627,10 @@ export const createPlainClient = (
       update: wrap(wrapParams, 'TeamSpaceMembership', 'update'),
       delete: wrap(wrapParams, 'TeamSpaceMembership', 'delete'),
     },
+    template: {
+      getMany: wrap(wrapParams, 'Template', 'getMany'),
+      get: wrap(wrapParams, 'Template', 'get'),
+    },
     uiConfig: {
       get: wrap(wrapParams, 'UIConfig', 'get'),
       update: wrap(wrapParams, 'UIConfig', 'update'),

test/unit/adapters/REST/endpoints/template.test.ts

@@ -0,0 +1,128 @@
+import { describe, test, expect } from 'vitest'
+import setupRestAdapter from '../helpers/setupRestAdapter'
+
+describe('Rest Template', { concurrent: true }, () => {
+  test('getMany calls correct URL', async () => {
+    const mockResponse = {
+      sys: { type: 'Array' },
+      limit: 100,
+      items: [],
+    }
+
+    const { httpMock, adapterMock } = setupRestAdapter(Promise.resolve({ data: mockResponse }))
+
+    return adapterMock
+      .makeRequest({
+        entityType: 'Template',
+        action: 'getMany',
+        userAgent: 'mocked',
+        params: {
+          spaceId: 'space123',
+          environmentId: 'master',
+          query: {},
+        },
+      })
+      .then((r) => {
+        expect(r).to.eql(mockResponse)
+        expect(httpMock.get.mock.calls[0][0]).to.eql(
+          '/spaces/space123/environments/master/templates',
+        )
+        expect(httpMock.get.mock.calls[0][1].params).to.eql({})
+      })
+  })
+
+  test('getMany passes pagination query parameters', async () => {
+    const mockResponse = {
+      sys: { type: 'Array' },
+      limit: 20,
+      items: [],
+    }
+
+    const { httpMock, adapterMock } = setupRestAdapter(Promise.resolve({ data: mockResponse }))
+
+    return adapterMock
+      .makeRequest({
+        entityType: 'Template',
+        action: 'getMany',
+        userAgent: 'mocked',
+        params: {
+          spaceId: 'space123',
+          environmentId: 'master',
+          query: {
+            limit: 20,
+            pageNext: 'next-page-token',
+          },
+        },
+      })
+      .then((r) => {
+        expect(r).to.eql(mockResponse)
+        expect(httpMock.get.mock.calls[0][0]).to.eql(
+          '/spaces/space123/environments/master/templates',
+        )
+        expect(httpMock.get.mock.calls[0][1].params).to.eql({
+          limit: 20,
+          pageNext: 'next-page-token',
+        })
+      })
+  })
+
+  test('getMany passes filter query parameters', async () => {
+    const mockResponse = {
+      sys: { type: 'Array' },
+      limit: 100,
+      items: [],
+    }
+
+    const { httpMock, adapterMock } = setupRestAdapter(Promise.resolve({ data: mockResponse }))
+
+    return adapterMock
+      .makeRequest({
+        entityType: 'Template',
+        action: 'getMany',
+        userAgent: 'mocked',
+        params: {
+          spaceId: 'space123',
+          environmentId: 'master',
+          query: {
+            order: 'sys.createdAt',
+          },
+        },
+      })
+      .then((r) => {
+        expect(r).to.eql(mockResponse)
+        expect(httpMock.get.mock.calls[0][0]).to.eql(
+          '/spaces/space123/environments/master/templates',
+        )
+        expect(httpMock.get.mock.calls[0][1].params).to.eql({
+          order: 'sys.createdAt',
+        })
+      })
+  })
+
+  test('get calls correct URL', async () => {
+    const mockResponse = {
+      sys: { id: 'template123', type: 'Template' },
+      name: 'Test Template',
+    }
+
+    const { httpMock, adapterMock } = setupRestAdapter(Promise.resolve({ data: mockResponse }))
+
+    return adapterMock
+      .makeRequest({
+        entityType: 'Template',
+        action: 'get',
+        userAgent: 'mocked',
+        params: {
+          spaceId: 'space123',
+          environmentId: 'master',
+          templateId: 'template123',
+        },
+      })
+      .then((r) => {
+        expect(r).to.eql(mockResponse)
+        expect(httpMock.get.mock.calls[0][0]).to.eql(
+          '/spaces/space123/environments/master/templates/template123',
+        )
+      })
+  })
+})