@stackbit/cms-contentstack 0.1.2-develop.2 → 0.1.2-staging.2

package/src/contentstack-content-source.ts

@@ -15,7 +15,7 @@ import {
     convertAssets,
     DocumentWithContext
 } from './contentstack-entries-converter';
-import { createEntryFromOperationFields, updateEntryFromUpdateOperations } from './contentstack-operation-converter';
+import { createEntryFromOperationFields, updateEntryFromUpdateOperations, GetLeanDocumentById } from './contentstack-operation-converter';
 import { getContentstackDashboardUrl, resolvePublishEnvironment, downloadFile, createWebhookIfNeeded, userMissingInMap } from './contentstack-utils';
 import { ContentPoller, getLastUpdatedEntityDate, SyncContext, SyncResult } from './contentstack-content-poller';
 import type { User, Asset, Entry, Environment, WebhookPayload } from './contentstack-types';
@@ -85,6 +85,7 @@ export class ContentstackContentSource
     private publishEnvironmentName?: string;
     private publishEnvironment!: Environment;
     private usersById: Record<string, User> = {};
+    private newUnsyncedEntryMap: Record<string, string> = {};
 
     constructor({ apiKey, managementToken, branch, authtoken, masterLocale, publishEnvironmentName, skipFetchOnStartIfCache }: ContentStackSourceOptions) {
         this.apiKey = apiKey;
@@ -214,6 +215,11 @@ export class ContentstackContentSource
                 } else {
                     const result = await this.convertSyncResult(syncResult);
                     await this.cache.updateContent(result);
+                    for (const document of result.documents) {
+                        if (this.newUnsyncedEntryMap[document.id]) {
+                            delete this.newUnsyncedEntryMap[document.id];
+                        }
+                    }
                 }
             }
         });
@@ -336,7 +342,7 @@ export class ContentstackContentSource
         let entries: Entry[];
         const cachedEntries = ((await this.cache.get('entries')) as Entry[]) ?? [];
         try {
-            if (this.syncContext.lastUpdatedEntryDate && cachedEntries) {
+            if (this.syncContext.lastUpdatedEntryDate && !_.isEmpty(cachedEntries)) {
                 entries = cachedEntries;
                 if (!this.skipFetchOnStartIfCache) {
                     this.logger.debug(
@@ -382,7 +388,7 @@ export class ContentstackContentSource
         let assets: Asset[];
         const cachedAssets = ((await this.cache.get('assets')) as Asset[]) ?? [];
         try {
-            if (this.syncContext.lastUpdatedAssetDate && cachedAssets) {
+            if (this.syncContext.lastUpdatedAssetDate && !_.isEmpty(cachedAssets)) {
                 assets = cachedAssets;
                 if (!this.skipFetchOnStartIfCache) {
                     this.logger.debug(`got ${cachedAssets.length} assets from cache, fetching assets updated after ${this.syncContext.lastUpdatedAssetDate}`);
@@ -439,11 +445,14 @@ export class ContentstackContentSource
         const entry = createEntryFromOperationFields({
             updateOperationFields: options.updateOperationFields,
             model: options.model,
-            getDocumentById: this.cache.getDocumentById,
+            getDocumentById: this.getCachedDocumentById.bind(this),
             getModelByName: this.cache.getModelByName,
             logger: this.logger
         });
         const newEntry = await this.contentStackClient.createEntry(options.model.name, entry);
+        // cache the created entry's uid and model name until it is received from Contentstack
+        // via onWebhook or contentPoller's notificationCallback methods.
+        this.newUnsyncedEntryMap[newEntry.uid] = options.model.name;
         return { documentId: newEntry.uid };
     }
 
@@ -458,13 +467,28 @@ export class ContentstackContentSource
         const updatedEntry = updateEntryFromUpdateOperations({
             entry,
             updateOperations: operations,
-            getDocumentById: this.cache.getDocumentById,
+            getDocumentById: this.getCachedDocumentById.bind(this),
             getModelByName: this.cache.getModelByName,
             logger: this.logger
         });
         await this.contentStackClient.updateEntry(updatedEntry);
     }
 
+    getCachedDocumentById(documentId: string): ReturnType<GetLeanDocumentById> {
+        const document = this.cache.getDocumentById(documentId);
+        if (document) {
+            return document;
+        }
+        if (this.newUnsyncedEntryMap[documentId]) {
+            this.logger.debug(`the created document ${documentId} was not yet fetched from Contentstack, using the cached document`);
+            return {
+                id: documentId,
+                modelName: this.newUnsyncedEntryMap[documentId]!
+            };
+        }
+        return;
+    }
+
     async deleteDocument(options: { document: StackbitTypes.Document<unknown>; userContext?: UserWithContext }): Promise<void> {
         this.logger.debug('deleteDocument');
         await this.contentStackClient.deleteEntry(options.document.modelName, options.document.id);
@@ -483,7 +507,7 @@ export class ContentstackContentSource
         let asset: Asset;
         try {
             if (options.base64) {
-                // TODO: write to .stackbit/cache folder
+                // TODO: pass the path to .stackbit/cache folder in init() options and use it to write the temp file
                 await writeFile(tempName, Buffer.from(options.base64, 'base64'));
             } else {
                 await downloadFile(options.url!, tempName);
@@ -549,41 +573,31 @@ export class ContentstackContentSource
 
         this.logger.debug(`got webhook for ${webhookData.event} ${webhookData.module}`);
 
+        let unsyncedEntryUid: string | undefined;
+
         if (webhookData.module === 'entry') {
             switch (webhookData.event) {
                 case 'create':
-                case 'update': {
-                    if (userMissingInMap(this.usersById, webhookData.data.entry as Entry)) {
-                        await this.fetchUsers();
-                    }
-                    const document = convertEntry({
-                        entry: {
-                            ...webhookData.data.entry,
-                            content_type_uid: webhookData.data.content_type.uid,
-                            publish_details: [],
-                            _branch: webhookData.data.branch.uid
-                        } as unknown as Entry,
-                        status: webhookData.event === 'create' ? 'added' : 'modified',
-                        apiKey: this.apiKey,
-                        getModelByName: this.cache.getModelByName,
-                        usersById: this.usersById,
-                        publishEnvironment: this.publishEnvironment,
-                        logger: this.logger
-                    });
-                    updates.documents!.push(document);
-                    break;
-                }
+                case 'update':
                 case 'publish': {
-                    if (webhookData.data.environment.uid !== this.publishEnvironment.uid) {
+                    // Generally, entry publish webhooks created by the content source are already configured to filter
+                    // only the publishEnvironment. However, still check for the publish event environment in case the
+                    // webhook was manually changed.
+                    if (webhookData.event === 'publish' && webhookData.data.environment.uid !== this.publishEnvironment.uid) {
                         this.logger.debug(
                             `entry was published in an environment '${webhookData.data.environment.name}' ` +
                                 `different from the publish environment '${this.publishEnvironment.name}', ignoring the webhook'`
                         );
                         break;
                     }
+                    if (webhookData.event === 'create' && webhookData.data.entry.uid in this.newUnsyncedEntryMap) {
+                        unsyncedEntryUid = webhookData.data.entry.uid;
+                    }
                     if (userMissingInMap(this.usersById, webhookData.data.entry as Entry)) {
                         await this.fetchUsers();
                     }
+                    const status: StackbitTypes.DocumentStatus =
+                        webhookData.event === 'publish' ? 'published' : webhookData.event === 'create' ? 'added' : 'modified';
                     const document = convertEntry({
                         entry: {
                             ...webhookData.data.entry,
@@ -591,7 +605,7 @@ export class ContentstackContentSource
                             publish_details: [],
                             _branch: webhookData.data.branch.uid
                         } as unknown as Entry,
-                        status: 'published',
+                        status: status,
                         apiKey: this.apiKey,
                         getModelByName: this.cache.getModelByName,
                         usersById: this.usersById,
@@ -618,25 +632,9 @@ export class ContentstackContentSource
         } else if (webhookData.module === 'asset') {
             switch (webhookData.event) {
                 case 'create':
-                case 'update': {
-                    if (userMissingInMap(this.usersById, webhookData.data.asset as Asset)) {
-                        await this.fetchUsers();
-                    }
-                    const asset = convertAsset({
-                        asset: {
-                            ...webhookData.data.asset,
-                            publish_details: [],
-                            _branch: webhookData.data.branch.uid
-                        } as unknown as Asset,
-                        apiKey: this.apiKey,
-                        usersById: this.usersById,
-                        publishEnvironment: this.publishEnvironment
-                    });
-                    updates.assets!.push(asset);
-                    break;
-                }
+                case 'update':
                 case 'publish': {
-                    if (webhookData.data.environment.uid !== this.publishEnvironment.uid) {
+                    if (webhookData.event === 'publish' && webhookData.data.environment.uid !== this.publishEnvironment.uid) {
                         this.logger.debug(
                             `asset was published in an environment '${webhookData.data.environment.name}' ` +
                                 `different from the publish environment '${this.publishEnvironment.name}', ignoring the webhook'`
@@ -686,6 +684,10 @@ export class ContentstackContentSource
                 `deleted documents: ${updates.deletedDocumentIds?.length}, ` +
                 `deleted assets: ${updates.deletedAssetIds?.length}`
         );
-        this.cache.updateContent(updates);
+        await this.cache.updateContent(updates);
+
+        if (unsyncedEntryUid) {
+            delete this.newUnsyncedEntryMap[unsyncedEntryUid];
+        }
     }
 }

package/src/contentstack-operation-converter.ts

@@ -4,10 +4,9 @@ import * as StackbitTypes from '@stackbit/types';
 import type { EntryData } from '@contentstack/management/types/stack/contentType/entry';
 import type { Entry, Asset } from './contentstack-types';
 import type { ModelWithContext } from './contentstack-schema-converter';
-import type { DocumentWithContext } from './contentstack-entries-converter';
 
 type GetModelByName = (modelName: string) => ModelWithContext | undefined;
-type GetDocumentById = (documentId: string) => DocumentWithContext | undefined;
+export type GetLeanDocumentById = (documentId: string) => { id: string; modelName: string } | undefined;
 
 export function createEntryFromOperationFields({
     updateOperationFields,
@@ -18,7 +17,7 @@ export function createEntryFromOperationFields({
 }: {
     updateOperationFields: Record<string, StackbitTypes.UpdateOperationField>;
     model: ModelWithContext;
-    getDocumentById: GetDocumentById;
+    getDocumentById: GetLeanDocumentById;
     getModelByName: GetModelByName;
     logger: StackbitTypes.Logger;
 }): EntryData {
@@ -55,7 +54,7 @@ export function updateEntryFromUpdateOperations({
 }: {
     entry: Entry;
     updateOperations: StackbitTypes.UpdateOperation[];
-    getDocumentById: GetDocumentById;
+    getDocumentById: GetLeanDocumentById;
     getModelByName: GetModelByName;
     logger: StackbitTypes.Logger;
 }): Entry {
@@ -117,7 +116,7 @@ export function getUpdatedEntryAtFieldPathWithOperation({
     entry: Entry;
     updateOperation: StackbitTypes.UpdateOperation;
     model: ModelWithContext;
-    getDocumentById: GetDocumentById;
+    getDocumentById: GetLeanDocumentById;
     getModelByName: GetModelByName;
     logger: StackbitTypes.Logger;
 }): Entry {
@@ -378,7 +377,7 @@ function getValueForOperation({
     rootModel: ModelWithContext;
     entryFieldPath: (string | number)[];
     modelFieldPath: string[];
-    getDocumentById: GetDocumentById;
+    getDocumentById: GetLeanDocumentById;
     getModelByName: GetModelByName;
     errorPrefix: string;
     logger: StackbitTypes.Logger;
@@ -468,7 +467,7 @@ export function convertOperationFieldValue({
     isInList: boolean;
     entryFieldPath: (string | number)[];
     modelFieldPath: string[];
-    getDocumentById: GetDocumentById;
+    getDocumentById: GetLeanDocumentById;
     getModelByName: GetModelByName;
     errorPrefix: string;
 }): any {

package/src/contentstack-types.ts

@@ -284,6 +284,11 @@ export type Entry = ContentStackEntry & {
     updated_at: string;
     created_by: string;
     updated_by: string;
+    /**
+     * The entry's locale.
+     * Note, this can be different from the `publish_details.locale` if the
+     * entry was not localized for the published locale.
+     */
     locale?: string;
     tags?: string[];
     publish_details?: PublishDetails[];
@@ -297,23 +302,49 @@ export type PublishDetails = {
     environment: string;
     time: string;
     user: string;
+    /**
+     * The version of the entry that was published.
+     * If the entry_locale is provided, then the version is of that entry locale.
+     * Otherwise, it is a version of the entry's own locale.
+     */
     version: number;
     /**
-     * The locale of the published document.
-     * Note, the locale may be different from entry's own locale.
+     * The published locale.
+     * Note, the published locale may be different from the entry's locale if a
+     * non-localized entry was published.
+     *
+     * For example, a non-localized "fr-fr" entry can be published to the "fr-fr"
+     * locale. In this case, the entry will be published from the values stored
+     * in the entry of the fallback locale, e.g., 'en-us'. When this entry is
+     * fetched using the content delivery API with `locale=fr-fr` it will return
+     * the entry with `locale: 'en-us'`, and `publish_details.locale: 'fr-fr'`.
+     *
+     * If an entry was not published to a `fr-fr` locale but was published to its
+     * fallback locale, then it will be returned from the Content Delivery API
+     * for `locale=fr-fr` parameter only if it also has `include_fallback=false`.
+     * In other words, non-published locales will be returned only when
+     * `include_fallback=true`.
      */
     locale: string;
     /**
-     * The 'entry_locale' specified the original entry locale under which the
-     * entry was published, it may be different from the 'locale'.
+     * The 'publish_details.entry_locale' specifies the original entry locale
+     * from which the entry was published, and it may be different from the
+     * 'publish_details.locale' if the entry was localized after it was published.
+     *
+     * It also specifies the entry's locale the version field relates to.
      *
-     * 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.
+     * For example, if an entry with locale "en-us" has been published to "fr-fr"
+     * locale without having a localized entry for "fr-fr". Then, when the entry
+     * is fetched with the locale=fr-fr filter, the `publish_details.locale`
+     * will be set to "fr-fr", but the entry's locale will remain "en-us" because
+     * it was not localized, and the `publish_details.entry_locale` will be undefined.
+     * Then, if the entry will be localized to "fr-fr" locale, the locale of
+     * the entry will be changed to "fr-fr", the `publish_details.locale` will
+     * remain "fr-fr" and the `publish_details.entry_locale` will be set to
+     * "en-us" specifying that the published entry's locale doesn't match the
+     * current's entry locale. Only after the localized "fr-fr" entry will be
+     * published to "fr-fr", then the `publish_details.entry_locale` will be set
+     * back to undefined.
      */
     entry_locale?: string;
 };