@stackbit/cms-contentstack 0.1.1-staging.0

package/src/contentstack-types.ts

@@ -0,0 +1,527 @@
+import type { Stack as ContentStackStack } from '@contentstack/management/types/stack';
+import type { User as ContentStackUser } from '@contentstack/management/types/user';
+import type { ContentType as ContentStackContentType } from '@contentstack/management/types/stack/contentType';
+import type { GlobalField as ContentStackGlobalField } from '@contentstack/management/types/stack/globalField';
+import type { Environment as ContentStackEnvironment } from '@contentstack/management/types/stack/environment';
+import type { Entry as ContentStackEntry } from '@contentstack/management/types/stack/contentType/entry';
+import type { Asset as ContentStackAsset } from '@contentstack/management/types/stack/asset';
+import type { Webhook as ContentStackWebhook, WebhookDestination as ContentStackWebhookDestination } from '@contentstack/management/types/stack/webhook';
+
+// Stack
+// =====
+
+export type Stack = ContentStackStack & {
+    uid: string;
+    name: string;
+    api_key: string;
+    org_uid: string;
+    master_locale: string;
+    created_at: string;
+    updated_at: string;
+};
+
+// User
+// ====
+
+export type User = ContentStackUser & {
+    uid: string;
+    created_at?: string;
+    updated_at?: string;
+    email?: string;
+    username?: string;
+    first_name?: string;
+    last_name?: string;
+    active?: boolean;
+};
+
+// Models
+// ======
+
+export type GlobalField = ContentStackGlobalField & {
+    uid: string;
+    title: string;
+    description?: string;
+    created_at?: string;
+    updated_at?: string;
+    urlPath?: string;
+    _version?: number;
+    _branch?: string;
+    inbuilt_class?: boolean;
+    last_activity?: unknown;
+    maintain_revisions?: boolean;
+    schema: ContentStackField[];
+};
+
+export type ContentType = ContentStackContentType & {
+    uid: string;
+    title: string;
+    description?: string;
+    created_at?: string;
+    updated_at?: string;
+    _version?: number;
+    _branch?: string;
+    inbuilt_class?: boolean;
+    last_activity?: unknown;
+    maintain_revisions?: boolean;
+    DEFAULT_ACL?: unknown;
+    SYS_ACL?: unknown;
+    options?: {
+        is_page: boolean;
+        singleton: boolean;
+        sub_title: any[];
+        title: string;
+        url_pattern?: string;
+        url_prefix?: string;
+    };
+    abilities?: {
+        get_one_object: boolean;
+        get_all_objects: boolean;
+        create_object: boolean;
+        update_object: boolean;
+        delete_object: boolean;
+        delete_all_objects: boolean;
+    };
+    schema: ContentStackField[];
+};
+
+export type ContentStackField =
+    | ContenteStackFieldText
+    | ContentStackFieldBoolean
+    | ContentStackFieldJson
+    | ContentStackFieldFile
+    | ContentStackFieldDate
+    | ContentStackFieldNumber
+    | ContentStackFieldLink
+    | ContentStackFieldGroup
+    | ContentStackFieldGlobalField
+    | ContentStackFieldReference
+    | ContentStackFieldBlocks;
+
+export type ContentStackFieldCommon = {
+    uid: string;
+    display_name: string;
+    mandatory: boolean;
+    multiple: boolean;
+    non_localizable: boolean;
+    unique: boolean;
+    field_metadata: {
+        description?: string;
+        placeholder?: string;
+        instruction?: string;
+        default_value?: any;
+    };
+};
+
+export type ContenteStackFieldText = ContentStackFieldCommon &
+    ContentStackFieldEnumCommon<string> & {
+        data_type: 'text';
+        format?: string;
+        // reference_to for allowed models when rich-text is used
+        reference_to: string[];
+        field_metadata?: {
+            _default?: boolean;
+            // multiline text
+            multiline?: boolean;
+            // markdown text
+            markdown?: boolean;
+            // rich-text
+            allow_rich_text?: boolean;
+            rich_text_type?: 'basic' | 'advanced' | 'custom';
+            // allowed rich-text options, e.g., h1, h2, bold, italic, etc.
+            options?: string[];
+            ref_multiple_content_types?: boolean;
+            // allows embedding entries into rich-text
+            embed_entry?: boolean;
+            // default key for enum options when advanced enum is used
+            default_key?: string;
+        };
+    };
+
+export type ContentStackFieldEnumCommon<ValueType> = {
+    // display type for enums. The 'dropdown' and 'radio' used on single enum
+    // values, while 'dropdown' and 'checkbox' for list of enums.
+    display_type?: 'dropdown' | 'checkbox' | 'radio';
+    // enum options when enum is used
+    enum?: ContentStackEnumOptions<ValueType>;
+};
+
+export type ContentStackEnumOptions<ValueType> = ContentStackEnumOptionsSimple<ValueType> | ContentStackEnumOptionsAdvanced<ValueType>;
+
+export type ContentStackEnumOptionsSimple<ValueType> = {
+    advanced: false;
+    choices: {
+        value: ValueType;
+    }[];
+};
+
+export type ContentStackEnumOptionsAdvanced<ValueType> = {
+    advanced: true;
+    choices: {
+        key: string;
+        value: ValueType;
+    }[];
+};
+
+export type ContentStackFieldBoolean = ContentStackFieldCommon & {
+    data_type: 'boolean';
+};
+
+export type ContentStackFieldJson = ContentStackFieldCommon & {
+    data_type: 'json';
+    format?: string;
+    // reference_to for allowed models when rich-text is used
+    reference_to?: string[];
+    field_metadata: {
+        allow_json_rte?: boolean;
+        embed_entry?: boolean;
+        multiline?: boolean;
+        rich_text_type?: 'basic' | 'advanced' | 'custom';
+        // allowed rich-text options, e.g., h1, h2, bold, italic, etc.
+        options?: string[];
+        ref_multiple_content_types?: boolean;
+    };
+};
+
+export type ContentStackFieldFile = ContentStackFieldCommon & {
+    data_type: 'file';
+    field_metadata: {
+        rich_text_type?: 'standard';
+        image?: boolean;
+    };
+    // file size limit
+    min?: number;
+    max?: number;
+    // image dimension limit
+    dimension?: {
+        width: ImageDimensions;
+        height: ImageDimensions;
+    };
+};
+
+export type ImageDimensions = {
+    min?: number | null;
+    max?: number | null;
+};
+
+export type ContentStackFieldDate = ContentStackFieldCommon & {
+    data_type: 'isodate';
+    startDate?: string | null;
+    endDate?: string | null;
+    field_metadata: {
+        hide_time?: boolean;
+        date_range?: boolean;
+        default_value?: {
+            custom: boolean;
+            date?: string;
+            time?: string;
+        };
+    };
+};
+
+export type ContentStackFieldNumber = ContentStackFieldCommon &
+    ContentStackFieldEnumCommon<number> & {
+        data_type: 'number';
+        min?: number | null;
+        max?: number | null;
+    };
+
+export type ContentStackFieldLink = ContentStackFieldCommon & {
+    data_type: 'link';
+    field_metadata: {
+        default_value?: {
+            title?: string;
+            url?: string;
+        };
+    };
+};
+
+export type ContentStackFieldGroup = ContentStackFieldCommon & {
+    data_type: 'group';
+    schema: ContentStackField[];
+};
+
+export type ContentStackFieldGlobalField = ContentStackFieldCommon & {
+    data_type: 'global_field';
+    reference_to: string;
+};
+
+export type ContentStackFieldReference = ContentStackFieldCommon & {
+    data_type: 'reference';
+    reference_to?: string[];
+    field_metadata: {
+        ref_multiple: boolean;
+        ref_multiple_content_types: boolean;
+    };
+};
+
+export type ContentStackFieldBlocks = Omit<ContentStackFieldCommon, 'multiple'> & {
+    data_type: 'blocks';
+    multiple: true;
+    blocks: (ContentStackFieldBlockItemSimple | ContentStackFieldBlockItemGlobalField)[];
+};
+
+export type ContentStackFieldBlockItemGlobalField = {
+    uid: string;
+    title: string;
+    reference_to: string;
+};
+
+export type ContentStackFieldBlockItemSimple = {
+    uid: string;
+    title: string;
+    schema: ContentStackField[];
+};
+
+// Entries
+// =======
+
+export type Entry = ContentStackEntry & {
+    uid: string;
+    content_type_uid: string;
+    title: string;
+    url?: string;
+    created_at: string;
+    updated_at: string;
+    created_by: string;
+    updated_by: string;
+    locale?: string;
+    tags?: string[];
+    publish_details?: PublishDetails[];
+    ACL?: unknown;
+    _branch?: string;
+    _version?: number;
+    _in_progress?: boolean;
+};
+
+export type PublishDetails = {
+    environment: string;
+    time: string;
+    user: string;
+    version: number;
+    /**
+     * The locale of the published document.
+     * Note, the locale may be different from entry's own locale.
+     */
+    locale: string;
+    /**
+     * The 'entry_locale' specified the original entry locale under which the
+     * entry was published, it may be different from the 'locale'.
+     *
+     * For example, if an entry with locale "A" has been published to locale "B",
+     * for which it isn't localized. Then the 'locale' will be locale "B", while
+     * the entry's own locale will remain "A" (because it is not localized),
+     * even when entries are fetched with locale=B filter.
+     * But, once the entry will be localized to locale "B", the 'entry_locale'
+     * will be set to locale "A", and the 'locale' will be set to locale "B"
+     * matching the entry's own locale.
+     */
+    entry_locale?: string;
+};
+
+// Assets
+// ======
+
+export type Asset = ContentStackAsset & {
+    uid: string;
+    title?: string;
+    description?: string;
+    created_at: string;
+    updated_at: string;
+    created_by: string;
+    updated_by: string;
+    content_type?: string;
+    file_size?: string;
+    tags?: string[];
+    filename?: string;
+    url?: string;
+    ACL?: unknown;
+    is_dir?: boolean;
+    parent_uid?: unknown;
+    _version?: number;
+    _branch?: string;
+    publish_details?: PublishDetails[];
+};
+
+// Locales
+// =======
+
+export type ContentStackLocale = {
+    uid: string;
+    code: string;
+    name: string;
+    fallback_locale?: string | null;
+    created_by?: string;
+    updated_by?: string;
+    created_at?: string;
+    updated_at?: string;
+    ACL?: unknown;
+    _version?: number;
+    _branch?: string;
+};
+
+// Environments
+// ============
+
+export type Environment = ContentStackEnvironment & {
+    uid: string;
+    name: string;
+    urls?: any[];
+    ACL?: unknown;
+    created_at?: string;
+    updated_at?: string;
+    created_by?: string;
+    updated_by?: string;
+    _version?: number;
+};
+
+// Webhooks
+// ========
+
+export type Webhook = ContentStackWebhook & {
+    uid: string;
+    name: string;
+    destinations: WebhookDestination[];
+    channels?: string[];
+    branches: string[];
+    retry_policy: string;
+    disabled: boolean;
+    concise_payload: boolean;
+    notifiers: unknown[];
+    applikation_id?: string;
+    app_user_object_uid: string;
+    org_uid?: string;
+    created_at?: string;
+    updated_at?: string;
+    updated_by?: string;
+    created_by?: string;
+};
+
+export type WebhookDestination = ContentStackWebhookDestination & {
+    target_url: string;
+    http_basic_auth?: string;
+    http_basic_password?: string;
+    custom_header?: {
+        header_name?: string;
+        value?: string;
+    }[];
+};
+
+export type WebhookPayload = WebhookPayloadEntry | WebhookPayloadAsset | WebhookPayloadContentType | WebhookPayloadGlobalField;
+
+export type WebhookPayloadBasicEvent = 'create' | 'update' | 'delete';
+
+export type WebhookPayloadCommonProps = {
+    api_key?: string;
+    triggered_at?: string;
+};
+
+export type WebhookPayloadEntry = WebhookPayloadCommonProps & {
+    module: 'entry';
+    data: {
+        content_type: {
+            uid: string;
+        };
+        branch: WebhookPayloadBranch;
+    };
+} & (
+        | {
+              event: WebhookPayloadBasicEvent;
+              data: {
+                  entry: Omit<Entry, 'content_type_uid' | 'publish_details' | '_branch'>;
+              };
+          }
+        | {
+              event: 'publish';
+              data: {
+                  action: 'publish';
+                  status: string;
+                  locale: string;
+                  environment: Environment;
+                  entry: Omit<Entry, 'content_type_uid' | 'publish_details' | '_branch'> & {
+                      publish_details?: Omit<PublishDetails, 'version'>;
+                  };
+              };
+          }
+        | {
+              event: 'unpublish';
+              data: {
+                  action: 'unpublish';
+                  status: string;
+                  locale: string;
+                  environment: Environment;
+                  entry: Omit<Entry, 'content_type_uid' | '_branch' | 'publish_details'>;
+              };
+          }
+    );
+
+export type WebhookPayloadAsset = WebhookPayloadCommonProps & {
+    module: 'asset';
+    data: {
+        branch: WebhookPayloadBranch;
+    };
+} & (
+        | {
+              event: WebhookPayloadBasicEvent;
+              data: {
+                  asset: Omit<Asset, '_branch' | 'publish_details'>;
+              };
+          }
+        | {
+              event: 'publish';
+              data: {
+                  // only when event is publish or unpublish
+                  action: 'publish';
+                  status: string;
+                  locale: string;
+                  environment: Environment;
+                  asset: Omit<Asset, '_branch' | 'publish_details'> & {
+                      publish_details?: Omit<PublishDetails, 'version'>;
+                  };
+              };
+          }
+        | {
+              event: 'unpublish';
+              data: {
+                  action: 'unpublish';
+                  status: string;
+                  locale: string;
+                  environment: Environment;
+                  asset: Omit<Asset, '_branch' | 'publish_details'>;
+              };
+          }
+    );
+
+export type WebhookPayloadContentType = WebhookPayloadCommonProps & {
+    module: 'content_type';
+    event: WebhookPayloadBasicEvent;
+    data: {
+        uid: string;
+        title: string;
+        description: string;
+        created_at: string;
+        updated_at: string;
+        schema: unknown;
+        options: unknown;
+        branch: WebhookPayloadBranch;
+    };
+};
+
+export type WebhookPayloadGlobalField = WebhookPayloadCommonProps & {
+    module: 'global_field';
+    event: WebhookPayloadBasicEvent;
+    data: {
+        uid: string;
+        title: string;
+        description: string;
+        created_at: string;
+        updated_at: string;
+        schema: unknown;
+        branch: WebhookPayloadBranch;
+    };
+};
+
+export type WebhookPayloadBranch = {
+    uid: string;
+    source: string;
+    alias: [];
+};

package/src/contentstack-utils.ts

@@ -0,0 +1,174 @@
+import { createWriteStream } from 'fs';
+import axios from 'axios';
+import type { Logger } from '@stackbit/types';
+import type { Asset, Entry, Environment, User } from './contentstack-types';
+import type { ContentStackClient } from './contentstack-api-client';
+
+export function getContentstackDashboardUrl({ apiKey, branch }: { apiKey: string; branch?: string }) {
+    branch = branch ? `?branch=${branch}` : '';
+    return getUrl(apiKey, `/dashboard${branch}`);
+}
+
+export function getEntryUrl({ apiKey, entry }: { apiKey: string; entry: Entry }) {
+    const branch = entry._branch ? `?branch=${entry._branch}` : '';
+    return getUrl(apiKey, `/content-type/${entry.content_type_uid}/${entry.locale}/entry/${entry.uid}/edit${branch}`);
+}
+
+export function getAssetUrl({ apiKey, asset }: { apiKey: string; asset: Asset }) {
+    const branch = asset._branch ? `?branch=${asset._branch}` : '';
+    return getUrl(apiKey, `/assets/${asset.uid}${branch}`);
+}
+
+function getUrl(apiKey: string, path: string) {
+    const baseUrl = 'https://app.contentstack.com/#!/stack/';
+    return `${baseUrl}${apiKey}${path}`;
+}
+
+export function userMissingInMap(usersById: Record<string, User>, entity: Entry | Asset) {
+    return !usersById[entity.created_by] || !usersById[entity.updated_by];
+}
+
+export function resolvePublishEnvironment({
+    environments,
+    publishEnvironmentName,
+    logger
+}: {
+    environments: Environment[];
+    publishEnvironmentName?: string;
+    logger: Logger;
+}): Environment {
+    if (publishEnvironmentName) {
+        const resolvedEnv = environments.find((env) => env.name === publishEnvironmentName);
+        if (resolvedEnv) {
+            return resolvedEnv;
+        }
+        logger.warn(
+            `The 'publishEnvironmentName' '${publishEnvironmentName}' provided to ContentStackSource constructor ` +
+                `does not match any environment name: [${environments.map((env) => env.name).join(', ')}]`
+        );
+    }
+    if (environments.length === 1) {
+        const resolvedEnv = environments[0]!;
+        logger.info(`The Contentstack stack has a single '${resolvedEnv.name}' environment, using it for publishing content`);
+        return resolvedEnv;
+    }
+    throw new Error(
+        `Stack has multiple environments: [${environments.map((env) => env.name).join(', ')}], ` +
+            `please specify one of them using the 'publishEnvironmentName' property in the ContentStackSource constructor options`
+    );
+}
+
+export async function createWebhookIfNeeded({
+    webhookUrl,
+    publishEnvironmentName,
+    branch,
+    isLocalDev,
+    contentStackClient,
+    logger
+}: {
+    webhookUrl?: string;
+    publishEnvironmentName: string;
+    branch?: string;
+    isLocalDev: boolean;
+    contentStackClient: ContentStackClient;
+    logger: Logger;
+}) {
+    if (!webhookUrl) {
+        return;
+    }
+    logger.debug(`webhook URL: ${webhookUrl}`);
+    const webhooks = await contentStackClient.getWebhooks();
+    if (isLocalDev) {
+        const localDevWebhookName = 'Stackbit local-dev webhook';
+        const localDevWebhook = webhooks.find((webhook) => webhook.name === localDevWebhookName);
+        if (localDevWebhook) {
+            const hasTargetUrlToWebhookUrl = localDevWebhook.destinations.find((destination) => destination.target_url === webhookUrl);
+            const hasBranch = !branch || localDevWebhook.branches.includes(branch);
+            if (!localDevWebhook.disabled && hasBranch && hasTargetUrlToWebhookUrl) {
+                logger.debug(
+                    `found enabled webhook '${localDevWebhookName}' for [${localDevWebhook.branches.join(', ')}] branch(es) and target_url '${webhookUrl}'`
+                );
+                return localDevWebhook;
+            }
+            logger.debug(
+                `found ${localDevWebhook.disabled ? 'disabled' : 'enabled'} webhook '${localDevWebhookName}' ` +
+                    `for [${localDevWebhook.branches.join(', ')}] branch(es) ` +
+                    `and target_url '${localDevWebhook.destinations[0]?.target_url}', resetting webhook`
+            );
+            const webhook = await contentStackClient.updateWebhook({
+                webhookId: localDevWebhook.uid,
+                webhookUrl,
+                branch
+            });
+            logger.debug(`webhook ${webhook.name} updated`);
+        } else {
+            logger.debug(`no webhook named '${localDevWebhookName}' was found, creating a webhook for branch '${branch}' and target_url '${webhookUrl}'`);
+            const webhook = await contentStackClient.createWebhook({
+                webhookName: localDevWebhookName,
+                webhookUrl,
+                publishEnvironmentName,
+                branch
+            });
+            logger.debug(`webhook ${webhook.name} created`);
+        }
+    } else {
+        const matchedWebhook = webhooks.find((webhook) => {
+            return webhook.destinations.find((destination) => destination.target_url === webhookUrl);
+        });
+        if (matchedWebhook) {
+            const hasBranch = !branch || matchedWebhook.branches.includes(branch);
+            if (!matchedWebhook.disabled && hasBranch) {
+                logger.debug(
+                    `found enabled webhook '${matchedWebhook.name}' for [${matchedWebhook.branches.join(', ')}] branch(es) and target_url '${webhookUrl}'`
+                );
+                return matchedWebhook;
+            }
+            logger.debug(
+                `found ${matchedWebhook.disabled ? 'disabled' : 'enabled'} webhook '${matchedWebhook.name}' ` +
+                    `for [${matchedWebhook.branches.join(', ')}] branch(es) ` +
+                    `and target_url '${matchedWebhook.destinations[0]?.target_url}', resetting webhook`
+            );
+            const webhook = await contentStackClient.updateWebhook({
+                webhookId: matchedWebhook.uid,
+                webhookUrl,
+                branch
+            });
+            logger.debug(`webhook ${webhook.name} updated`);
+        } else {
+            logger.debug(`no webhook matching the provided webhookUrl was found, creating a webhook for branch '${branch}' and target_url '${webhookUrl}'`);
+            const webhook = await contentStackClient.createWebhook({
+                webhookName: 'Stackbit webhook',
+                webhookUrl,
+                publishEnvironmentName,
+                branch
+            });
+            logger.debug(`webhook ${webhook.name} created`);
+        }
+    }
+}
+
+export async function downloadFile(fileUrl: string, outputLocationPath: string) {
+    const writer = createWriteStream(outputLocationPath);
+    const response = await axios({
+        method: 'get',
+        url: fileUrl,
+        responseType: 'stream'
+    });
+
+    response.data.pipe(writer);
+
+    return new Promise((resolve, reject) => {
+        let error: Error | null = null;
+        writer.on('error', (err) => {
+            error = err;
+            writer.close();
+            reject(err);
+        });
+
+        writer.on('close', () => {
+            if (!error) {
+                resolve(true);
+            }
+        });
+    });
+}

package/src/index.ts

@@ -0,0 +1,3 @@
+export * from './contentstack-content-source';
+export type { ModelContext, ModelWithContext } from './contentstack-schema-converter';
+export type { DocumentContext, DocumentWithContext, AssetContext, AssetWithContext } from './contentstack-entries-converter';