contentful-management.js - v7.19.1

Type declaration

• apiAdapter: Adapter

Type declaration

• accessToken: string

• Optional description?: undefined | string

• environments: { sys: MetaLinkProps }[]

• name: string

• Optional policies?: { action: string; effect: string }[]

• preview_api_key: { sys: MetaLinkProps }

  • sys: MetaLinkProps

• sys: MetaSysProps

Type declaration

• md5: string

• name: string

• size: number

Type declaration

• Optional comment?: undefined | string

  A comment that describes this bundle

• files: AppBundleFile[]

  List of all the files that are in this bundle

• sys: AppBundleSys

  System metadata

Type declaration

• Optional bundle?: Link<"AppBundle">

  Link to an AppBundle

• Optional locations?: AppLocation[]

  Locations where the app can be installed

• name: string

  App name

• Optional parameters?: undefined | { instance?: ParameterDefinition[] }

  Instance parameter definitions

• Optional src?: undefined | string

  URL where the root HTML document of the app can be found

• sys: BasicMetaSysProps & { organization: SysLink }

  System metadata

Type declaration

• Optional parameters?: FreeFormParameters

  Free-form installation parameters (API limits stringified length to 16kB)

• sys: BasicMetaSysProps & { appDefinition: SysLink; environment: SysLink; space: SysLink }

Type declaration

• sys: AppUploadSys & { expiresAt: string; organization: SysLink }

Type declaration

• archive: function

  • archive(): Promise<Asset>

  • Archives the object

    example

    const contentful = require('contentful-management')
    
    const client = contentful.createClient({
      accessToken: '<content_management_api_key>'
    })
    
    client.getSpace('<space_id>')
    .then((space) => space.getEnvironment('<environment_id>'))
    .then((environment) => environment.getAsset('<asset_id>'))
    .then((asset) => asset.archive())
    .then((asset) => console.log(`Asset ${asset.sys.id} archived.`)
    .catch(console.error)
    

    Returns Promise<Asset>

    Object returned from the server with updated metadata.

• delete: function

  • delete(): Promise<void>

  • Deletes this object on the server.

    example

    const contentful = require('contentful-management')
    
    const client = contentful.createClient({
      accessToken: '<content_management_api_key>'
    })
    
    client.getSpace('<space_id>')
    .then((space) => space.getEnvironment('<environment_id>'))
    .then((environment) => environment.getAsset('<asset_id>'))
    .then((asset) => asset.delete())
    .then((asset) => console.log(`Asset deleted.`)
    .catch(console.error)
    

    Returns Promise<void>

    Promise for the deletion. It contains no data, but the Promise error case should be handled.

• isArchived: function

  • isArchived(): boolean

  • Checks if asset is archived. This means it's not exposed to the Delivery/Preview APIs.

    Returns boolean

• isDraft: function

  • isDraft(): boolean

  • Checks if the asset is in draft mode. This means it is not published.

    Returns boolean

• isPublished: function

  • isPublished(): boolean

  • Checks if the asset is published. A published asset might have unpublished changes

    Returns boolean

• isUpdated: function

  • isUpdated(): boolean

  • Checks if the asset is updated. This means the asset was previously published but has unpublished changes.

    Returns boolean

• processForAllLocales: function

  • processForAllLocales(options?: AssetProcessingForLocale): Promise<Asset>

  • Triggers asset processing after an upload, for the files uploaded to all locales of an asset.

    prop

    options.processingCheckWait - Time in milliseconds to wait before checking again if the asset has been processed (default: 500ms)

    prop

    options.processingCheckRetries - Maximum amount of times to check if the asset has been processed (default: 5)

    throws

    {AssetProcessingTimeout} If the asset takes too long to process. If this happens, retrieve the asset again, and if the url property is available, then processing has succeeded. If not, your file might be damaged.

    example

    const contentful = require('contentful-management')
    
    const client = contentful.createClient({
      accessToken: '<content_management_api_key>'
    })
    client.getSpace('<space_id>')
    .then((space) => space.getEnvironment('<environment_id>'))
    .then((environment) => environment.createAssetWithId('<asset_id>', {
      title: {
        'en-US': 'Playsam Streamliner',
        'de-DE': 'Playsam Streamliner'
      },
      file: {
        'en-US': {
          contentType: 'image/jpeg',
          fileName: 'example.jpeg',
          upload: 'https://example.com/example.jpg'
        },
        'de-DE': {
          contentType: 'image/jpeg',
          fileName: 'example.jpeg',
          upload: 'https://example.com/example-de.jpg'
        }
      }
    }))
    .then((asset) => asset.processForAllLocales())
    .then((asset) => console.log(asset))
    .catch(console.error)
    

    Parameters

    • Optional options: AssetProcessingForLocale

      Additional options for processing

    Returns Promise<Asset>

    Object returned from the server with updated metadata.

• processForLocale: function

  • processForLocale(locale: string, Options?: AssetProcessingForLocale): Promise<Asset>

  • Triggers asset processing after an upload, for the file uploaded to a specific locale.

    prop

    options.processingCheckWait - Time in milliseconds to wait before checking again if the asset has been processed (default: 500ms)

    prop

    options.processingCheckRetries - Maximum amount of times to check if the asset has been processed (default: 5)

    throws

    {AssetProcessingTimeout} If the asset takes too long to process. If this happens, retrieve the asset again, and if the url property is available, then processing has succeeded. If not, your file might be damaged.

    example

    const contentful = require('contentful-management')
    
    const client = contentful.createClient({
      accessToken: '<content_management_api_key>'
    })
    client.getSpace('<space_id>')
    .then((space) => space.getEnvironment('<environment_id>'))
    .then((environment) => environment.createAssetWithId('<asset_id>', {
      title: {
        'en-US': 'Playsam Streamliner',
      },
      file: {
        'en-US': {
          contentType: 'image/jpeg',
          fileName: 'example.jpeg',
          upload: 'https://example.com/example.jpg'
        }
      }
    }))
    .then((asset) => asset.processForLocale('en-US'))
    .then((asset) => console.log(asset))
    .catch(console.error)
    

    Parameters

    • locale: string

      Locale which processing should be triggered for

    • Optional Options: AssetProcessingForLocale

    Returns Promise<Asset>

    Object returned from the server with updated metadata.

• publish: function

  • publish(): Promise<Asset>

  • Publishes the object

    example

    const contentful = require('contentful-management')
    
    const client = contentful.createClient({
      accessToken: '<content_management_api_key>'
    })
    
    client.getSpace('<space_id>')
    .then((space) => space.getEnvironment('<environment_id>'))
    .then((environment) => environment.getAsset('<asset_id>'))
    .then((asset) => asset.publish())
    .then((asset) => console.log(`Asset ${asset.sys.id} published.`)
    .catch(console.error)
    

    Returns Promise<Asset>

    Object returned from the server with updated metadata.

• unarchive: function

  • unarchive(): Promise<Asset>

  • Unarchives the object

    example

    const contentful = require('contentful-management')
    
    const client = contentful.createClient({
      accessToken: '<content_management_api_key>'
    })
    
    client.getSpace('<space_id>')
    .then((space) => space.getEnvironment('<environment_id>'))
    .then((environment) => environment.getAsset('<asset_id>'))
    .then((asset) => asset.unarchive())
    .then((asset) => console.log(`Asset ${asset.sys.id} unarchived.`)
    .catch(console.error)
    

    Returns Promise<Asset>

    Object returned from the server with updated metadata.

• unpublish: function

  • unpublish(): Promise<Asset>

  • Unpublishes the object

    example

    const contentful = require('contentful-management')
    
    const client = contentful.createClient({
      accessToken: '<content_management_api_key>'
    })
    
    client.getSpace('<space_id>')
    .then((space) => space.getEnvironment('<environment_id>'))
    .then((environment) => environment.getAsset('<asset_id>'))
    .then((asset) => asset.unpublish())
    .then((asset) => console.log(`Asset ${asset.sys.id} unpublished.`)
    .catch(console.error)
    

    Returns Promise<Asset>

    Object returned from the server with updated metadata.

• update: function

  • update(): Promise<Asset>

  • Sends an update to the server with any changes made to the object's properties

    example

    const contentful = require('contentful-management')
    
    const client = contentful.createClient({
      accessToken: '<content_management_api_key>'
    })
    
    client.getSpace('<space_id>')
    .then((space) => space.getEnvironment('<environment_id>'))
    .then((environment) => environment.getAsset('<asset_id>'))
    .then((asset) => {
      asset.fields.title['en-US'] = 'New asset title'
      return asset.update()
    })
    .then((asset) => console.log(`Asset ${asset.sys.id} updated.`)
    .catch(console.error)
    

    Returns Promise<Asset>

    Object returned from the server with updated changes.

Type declaration

• policy: string

  A JWT describing a policy; needs to be attached to signed URLs

• secret: string

  A secret key to be used for signing URLs

Type declaration

• fields: { description?: undefined | {}; file: {}; title: {} }

  • Optional description?: undefined | {}

    Description for this asset

  • file: {}

    File object for this asset

    • [key: string]: { contentType: string; details?: Record<string, any>; fileName: string; upload?: undefined | string; uploadFrom?: Record<string, any>; url?: undefined | string }

      • contentType: string

      • Optional details?: Record<string, any>

        Details for the file, depending on file type (example: image size in bytes, etc)

      • fileName: string

      • Optional upload?: undefined | string

        Url where the file is available to be downloaded from, into the Contentful asset system. After the asset is processed this field is gone.

      • Optional uploadFrom?: Record<string, any>

      • Optional url?: undefined | string

        Url where the file is available at the Contentful media asset system. This field won't be available until the asset is processed.

  • title: {}

    Title for this asset

    • [key: string]: string

• Optional metadata?: MetadataProps

• sys: EntityMetaSysProps

Type declaration

• Optional initialDelayMs?: undefined | number

  Initial delay in milliseconds when performing the first check. This is used to prevent short running bulkActions of waiting too long for a result.

  default

  1000 (1s)

• Optional retryCount?: undefined | number

  The amount of times to retry.

  default

  30

• Optional retryIntervalMs?: undefined | number

  The interval between retries, in milliseconds (ms).

  default

  2000 (2s)

• Optional throwOnFailedExecution?: undefined | false | true

  Throws an error if the BulkAction does not complete with a successful (succeeded) status.

  default

  true

Type declaration

• createdAt: ISO8601Timestamp

• createdBy: Link<"User">

• environment: Link<"Environment">

• id: string

• space: Link<"Space">

• status: BulkActionStatuses

• type: "BulkAction"

• updatedAt: ISO8601Timestamp

Type declaration

Type declaration

• delete: function

  • delete(): Promise<void>

  • Deletes this object on the server.

    example

    const contentful = require('contentful-management')
    
    const client = contentful.createClient({
      accessToken: '<content_management_api_key>'
    })
    
    client.getSpace('<space_id>')
    .then((space) => space.getEnvironment('<environment_id>'))
    .then((environment) => environment.getContentType('<contentType_id>'))
    .then((contentType) => contentType.delete())
    .then(() => console.log('contentType deleted'))
    .catch(console.error)
    

    Returns Promise<void>

    Promise for the deletion. It contains no data, but the Promise error case should be handled.

• getEditorInterface: function

  • getEditorInterface(): Promise<EditorInterface>

  • Gets the editor interface for the object
    Important note: The editor interface only represent a published contentType.
    To get the most recent representation of the contentType make sure to publish it first

    example

    const contentful = require('contentful-management')
    
    const client = contentful.createClient({
      accessToken: '<content_management_api_key>'
    })
    
    client.getSpace('<space_id>')
    .then((space) => space.getEnvironment('<environment_id>'))
    .then((environment) => environment.getContentType('<contentType_id>'))
    .then((contentType) => contentType.getEditorInterface())
    .then((editorInterface) => console.log(editorInterface.contorls))
    .catch(console.error)
    

    Returns Promise<EditorInterface>

    Object returned from the server with the current editor interface.

• getSnapshot: function

  • getSnapshot(snapshotId: string): Promise<SnapshotProps<ContentTypeProps>>

  • Gets a snapshot of a contentType

    example

    const contentful = require('contentful-management')
    
    const client = contentful.createClient({
      accessToken: '<content_management_api_key>'
    })
    
    client.getSpace('<space_id>')
    .then((space) => space.getEnvironment('<environment_id>'))
    .then((environment) => environment.getContentType('<contentType_id>'))
    .then((entry) => entry.getSnapshot('<snapshot-id>'))
    .then((snapshot) => console.log(snapshot))
    .catch(console.error)
    

    Parameters

    • snapshotId: string

      Id of the snapshot

    Returns Promise<SnapshotProps<ContentTypeProps>>

• getSnapshots: function

  • getSnapshots(): Promise<Collection<Snapshot<ContentTypeProps>, SnapshotProps<ContentTypeProps>>>

  • Gets all snapshots of a contentType

    example

    const contentful = require('contentful-management')
    
    const client = contentful.createClient({
      accessToken: '<content_management_api_key>'
    })
    
    client.getSpace('<space_id>')
    .then((space) => space.getEnvironment('<environment_id>'))
    .then((environment) => environment.getContentType('<contentType_id>'))
    .then((entry) => entry.getSnapshots())
    .then((snapshots) => console.log(snapshots.items))
    .catch(console.error)
    

    Returns Promise<Collection<Snapshot<ContentTypeProps>, SnapshotProps<ContentTypeProps>>>

• isDraft: function

  • isDraft(): boolean

  • Checks if the contentType is in draft mode. This means it is not published.

    Returns boolean

• isPublished: function

  • isPublished(): boolean

  • Checks if the contentType is published. A published contentType might have unpublished changes (@see {ContentType.isUpdated})

    Returns boolean

• isUpdated: function

  • isUpdated(): boolean

  • Checks if the contentType is updated. This means the contentType was previously published but has unpublished changes.

    Returns boolean

• omitAndDeleteField: function

  • omitAndDeleteField(id: string): Promise<ContentType>

  • Omits and deletes a field if it exists on the contentType. This is a convenience method which does both operations at once and potentially less safe than the standard way. See note about deleting fields on the Update method.

    Parameters

    • id: string

    Returns Promise<ContentType>

    Object returned from the server with updated metadata.

• publish: function

  • publish(): Promise<ContentType>

  • Publishes the object

    example

    const contentful = require('contentful-management')
    
    const client = contentful.createClient({
      accessToken: '<content_management_api_key>'
    })
    
    client.getSpace('<space_id>')
    .then((space) => space.getEnvironment('<environment_id>'))
    .then((environment) => environment.getContentType('<contentType_id>'))
    .then((contentType) => contentType.publish())
    .then((contentType) => console.log(`${contentType.sys.id} is published`))
    .catch(console.error)
    

    Returns Promise<ContentType>

    Object returned from the server with updated metadata.

• unpublish: function

  • unpublish(): Promise<ContentType>

  • Unpublishes the object

    example

    const contentful = require('contentful-management')
    
    const client = contentful.createClient({
      accessToken: '<content_management_api_key>'
    })
    
    client.getSpace('<space_id>')
    .then((space) => space.getEnvironment('<environment_id>'))
    .then((environment) => environment.getContentType('<contentType_id>'))
    .then((contentType) => contentType.unpublish())
    .then((contentType) => console.log(`${contentType.sys.id} is unpublished`))
    .catch(console.error)
    

    Returns Promise<ContentType>

    Object returned from the server with updated metadata.

• update: function

  • update(): Promise<ContentType>

  • Sends an update to the server with any changes made to the object's properties.
    Important note about deleting fields: The standard way to delete a field is with two updates: first omit the property from your responses (set the field attribute "omitted" to true), and then delete it by setting the attribute "deleted" to true. See the "Deleting fields" section in the API reference for more reasoning. Alternatively, you may use the convenience method omitAndDeleteField to do both steps at once.

    example

    const contentful = require('contentful-management')
    
    const client = contentful.createClient({
      accessToken: '<content_management_api_key>'
    })
    
    client.getSpace('<space_id>')
    .then((space) => space.getEnvironment('<environment_id>'))
    .then((environment) => environment.getContentType('<contentType_id>'))
    .then((contentType) => {
     contentType.name = 'New name'
     return contentType.update()
    })
    .then(contentType => console.log(contentType))
    .catch(console.error)
    

    Returns Promise<ContentType>

    Object returned from the server with updated changes.

Type declaration

• description: string

• displayField: string

  Field used as the main display field for Entries

• fields: ContentFields[]

  All the fields contained in this Content Type

• name: string

• sys: BasicMetaSysProps & { environment: SysLink; firstPublishedAt?: undefined | string; publishedCounter?: undefined | number; publishedVersion?: undefined | number; space: SysLink }

Type declaration

• appUploadId: string

• Optional comment?: undefined | string

Type declaration

• expiresAt: number

  (required) UNIX timestamp in the future (but not more than 48 hours from now)

Type declaration

• Optional environmentId?: undefined | string

• Optional organizationId?: undefined | string

• Optional spaceId?: undefined | string

Type declaration

• Optional controls?: Control[]

  Array of fields and it's associated widgetId

• Optional editor?: Editor

  Legacy singular editor override

• Optional editors?: Editor[]

  Array of editors. Defaults will be used if property is missing.

• Optional sidebar?: SidebarItem[]

  Array of sidebar widgerts. Defaults will be used if property is missing.

• sys: MetaSysProps & { contentType: { sys: MetaLinkProps }; environment: { sys: MetaLinkProps }; space: { sys: MetaLinkProps } }

Type declaration

• entity: VersionedLink<Entity> | Link<Entity>

• error: any

Type declaration

• Optional maxDepth?: undefined | number

Type declaration

• environment: { sys: MetaLinkProps }

  • sys: MetaLinkProps

• sys: BasicMetaSysProps & { space: SysLink }

  System meta data

Type declaration

• name: string

  Name of the environmant

• sys: EnvironmentMetaSys

  System metadata

Type declaration

• extension: { fieldTypes: FieldType[]; name: string; parameters?: undefined | { installation?: ParameterDefinition[]; instance?: ParameterDefinition[] }; sidebar?: undefined | false | true; src?: undefined | string; srcdoc?: undefined | string }

  • fieldTypes: FieldType[]

    Field types where an extension can be used

  • name: string

    Extension name

  • Optional parameters?: undefined | { installation?: ParameterDefinition[]; instance?: ParameterDefinition[] }

    Parameter definitions

  • Optional sidebar?: undefined | false | true

    Controls the location of the extension. If true it will be rendered on the sidebar instead of replacing the field's editing control

  • Optional src?: undefined | string

    URL where the root HTML document of the extension can be found

  • Optional srcdoc?: undefined | string

    String representation of the extension (e.g. inline HTML code)

• Optional parameters?: DefinedParameters

  Values for installation parameters

• sys: ExtensionSysProps

Type declaration

• organizationId: string

Type declaration

• environmentId: string

• spaceId: string

Type declaration

• spaceId: string

Type declaration

• organizationId: string

• teamId: string

Type declaration

• code: string

  Locale code (example: en-us)

• contentDeliveryApi: boolean

  If the content under this locale should be available on the CDA (for public reading)

• contentManagementApi: boolean

  If the content under this locale should be available on the CMA (for editing)

• default: boolean

  If this is the default locale

• fallbackCode: string | null

  Locale code to fallback to when there is not content for the current locale

• internal_code: string

  Internal locale code

• name: string

  Locale name

• optional: boolean

  If the locale needs to be filled in on entries or not

• sys: BasicMetaSysProps & { environment: SysLink; space: SysLink }