[DEV-12091] Declare slug property support to Story Create & Update APIs

Author: e1himself

src/endpoints/Stories/Client.ts

@@ -195,18 +195,21 @@ export class Client {
         return story;
     }
 
-    async create<Options extends IncludeOptions & { formats?: Formats }>(
+    async create<Options extends IncludeOptions & { formats?: Formats; force?: boolean }>(
         payload: CreateRequest,
-        options?: Exactly<Options, IncludeOptions & { formats?: Formats }>,
+        options?: Exactly<Options, IncludeOptions & { formats?: Formats; force?: boolean }>,
     ): Promise<ExtendedStory & InferExtraFields<Options>> {
-        const { include, formats } = options ?? {};
+        const { include, formats, force = false } = options ?? {};
 
         const { story } = await this.apiClient.post<{
             story: ExtendedStory & InferExtraFields<Options>;
         }>(routing.storiesUrl, {
             headers: acceptedFormatsHeader(formats),
+            query: {
+                include,
+                force: force || undefined,
+            },
             payload,
-            query: { include },
         });
         return story;
     }
@@ -252,15 +255,15 @@ export class Client {
         return story;
     }
 
-    async move<Options extends IncludeOptions & { force?: true; formats?: Formats }>(
+    async move<Options extends IncludeOptions & { formats?: Formats; force?: boolean }>(
         id: StoryId,
         payload: MoveRequest,
-        options?: Exactly<Options, IncludeOptions & { force?: true; formats?: Formats }>,
+        options?: Exactly<Options, IncludeOptions & { formats?: Formats; force?: boolean }>,
     ): Promise<
         | ChangeNewsroomSuccessResponse<ExtendedStory & InferExtraFields<Options>>
         | ChangeNewsroomUnsafeResponse
     > {
-        const { include, force, formats } = options ?? {};
+        const { include, formats, force = false } = options ?? {};
 
         const url = `${routing.storiesUrl}/${id}/move`;
 
@@ -269,7 +272,10 @@ export class Client {
                 story: ExtendedStory & InferExtraFields<Options>;
             }>(url, {
                 headers: acceptedFormatsHeader(formats),
-                query: { include: include as string[] | undefined, force },
+                query: {
+                    include,
+                    force: force || undefined, // only pass it if it's true
+                },
                 payload,
             });
 
@@ -282,20 +288,23 @@ export class Client {
         }
     }
 
-    async update<Options extends IncludeOptions & { formats?: Formats }>(
+    async update<Options extends IncludeOptions & { formats?: Formats; force?: boolean }>(
         id: StoryId,
         payload: UpdateRequest,
-        options?: Exactly<Options, IncludeOptions & { formats?: Formats }>,
+        options?: Exactly<Options, IncludeOptions & { formats?: Formats; force?: boolean }>,
     ): Promise<ExtendedStory & InferExtraFields<Options>> {
         const url = `${routing.storiesUrl}/${id}`;
-        const { include, formats } = options ?? {};
+        const { include, formats, force = false } = options ?? {};
 
         const { story } = await this.apiClient.patch<{
             story: ExtendedStory & InferExtraFields<Options>;
         }>(url, {
             headers: acceptedFormatsHeader(formats),
+            query: {
+                include,
+                force: force || undefined, // only pass it if it's true
+            },
             payload,
-            query: { include: include as string[] | undefined },
         });
         return story;
     }
@@ -316,7 +325,7 @@ export class Client {
         }>(url, {
             headers: acceptedFormatsHeader(formats),
             payload,
-            query: { include: include as string[] | undefined },
+            query: { include },
         });
         return story;
     }
@@ -337,7 +346,7 @@ export class Client {
         }>(url, {
             headers: acceptedFormatsHeader(formats),
             payload,
-            query: { include: include as string[] | undefined },
+            query: { include },
         });
         return story;
     }
@@ -355,7 +364,7 @@ export class Client {
         }>(url, {
             headers: acceptedFormatsHeader(formats),
             payload,
-            query: { include: include as string[] | undefined },
+            query: { include },
         });
         return story;
     }
@@ -373,7 +382,7 @@ export class Client {
         }>(url, {
             headers: acceptedFormatsHeader(formats),
             payload,
-            query: { include: include as string[] | undefined },
+            query: { include },
         });
         return story;
     }
@@ -391,7 +400,7 @@ export class Client {
         }>(url, {
             headers: acceptedFormatsHeader(formats),
             payload,
-            query: { include: include as string[] | undefined },
+            query: { include },
         });
         return story;
     }
@@ -409,24 +418,24 @@ export class Client {
         }>(url, {
             headers: acceptedFormatsHeader(formats),
             payload,
-            query: { include: include as string[] | undefined },
+            query: { include },
         });
         return story;
     }
 
-    async pin<Options extends IncludeOptions & { force?: boolean; formats?: Formats }>(
+    async pin<Options extends IncludeOptions & { formats?: Formats; force?: boolean }>(
         id: StoryId,
-        options?: Exactly<Options, IncludeOptions & { force?: boolean; formats?: Formats }>,
+        options?: Exactly<Options, IncludeOptions & { formats?: Formats; force?: boolean }>,
     ): Promise<ExtendedStory & InferExtraFields<Options>> {
         const url = `${routing.storiesUrl}/${id}/pin`;
-        const { include, force, formats } = options ?? {};
+        const { include, formats, force = false } = options ?? {};
 
         const { story } = await this.apiClient.post<{
             story: ExtendedStory & InferExtraFields<Options>;
         }>(url, {
             headers: acceptedFormatsHeader(formats),
             query: {
-                include: include as string[] | undefined,
+                include: include,
                 force: force || undefined,
             },
         });
@@ -444,7 +453,7 @@ export class Client {
             story: ExtendedStory & InferExtraFields<Options>;
         }>(url, {
             headers: acceptedFormatsHeader(formats),
-            query: { include: include as string[] | undefined },
+            query: { include: include },
         });
         return story;
     }

src/endpoints/Stories/types.ts

@@ -100,6 +100,16 @@ export interface ListResponse<S extends Story = Story> {
 }
 
 interface GenericCreateRequest {
+    /**
+     * Set a custom slug for a Story.
+     *
+     * - If there is another story with exactly the same slug value, the Create request will throw [HTTP 409 Conflict].
+     *
+     * - Conflicts can be force-resolved by passing `?force` GET parameter.
+     *   This will update other conflicting stories slugs to something else (i.e. adding random suffix).
+     */
+    slug?: Story['slug'];
+
     newsroom?: Newsroom['id'] | Newsroom['uuid'];
 
     published_at?: Iso8601DateTime;
@@ -117,6 +127,17 @@ interface GenericCreateRequest {
 }
 
 interface GenericUpdateRequest {
+    /**
+     * Set a custom slug for a Story.
+     * Updating it to `null` will revert back to automatically generated slugs.
+     *
+     * - If there is another story with exactly the same slug value, the Update request will throw [HTTP 409 Conflict].
+     *
+     * - Conflicts can be force-resolved by passing `?force` GET parameter.
+     *   This will update other conflicting stories slugs to something else (i.e. adding random suffix).
+     */
+    slug?: Story['slug'] | null;
+
     published_at?: Iso8601DateTime;
     visibility?: Story.Visibility;
     culture?: CultureRef['code'];