add parameter for the completion mode

packages/aitube-client/package.json

@@ -4,7 +4,7 @@
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "type": "module",
-  "version": "0.0.11",
+  "version": "0.0.12",
   "description": "Official API client for AiTube.at",
   "scripts": {
     "build": "bun build --target=node ./src/index.ts --outfile=dist/index.js && bun run build:declaration",

packages/aitube-client/src/api/editClapDialogues.ts

@@ -1,12 +1,26 @@
 import { ClapProject, fetchClap, serializeClap } from "@aitube/clap"
 
 import { aitubeApiUrl } from "@/config"
+import { ClapCompletionMode } from "./types"
 
 export async function editClapDialogues({
   clap,
+  completionMode = ClapCompletionMode.MERGE,
   token,
 }: {
   clap: ClapProject
+
+  /**
+   * Completion mode (optional, defaults to "merge")
+   * 
+   * Possible values are:
+   * - full: the API and the client will return a full clap file. This is a very convenient and simple mode, but it is also very ineficient, so it should not be used for intensive applications.
+   * - partial: the API and the client will return a partial clap file, containing only the new values and changes. This is useful for real-time applications and streaming.
+   * - merge: the API will return a partial clap file, and the client will return a merge of the original with the new values. This is safe to run, there are no side-effects.
+   * - replace: the API will return a partial clap file, and the client will replace the original. This is the most efficient mode, but it relies on side-effects and inline object updates. 
+   */
+  completionMode?: ClapCompletionMode
+
   token?: string
 }): Promise<ClapProject> {
 
@@ -14,7 +28,16 @@ export async function editClapDialogues({
   
   const hasToken = typeof token === "string" && token.length > 0
 
-  const newClap = await fetchClap(`${aitubeApiUrl}edit/dialogues`, {
+  const newClap = await fetchClap(
+    `${aitubeApiUrl}edit/dialogues${
+      typeof completionMode === "string"
+      ? `?c=${
+          completionMode === ClapCompletionMode.FULL
+          ? "full"
+          : "partial"
+        }`
+      : ""
+    }`, {
     method: "POST",
     headers: {
       "Content-Type": "application/x-gzip",

packages/aitube-client/src/api/editClapEntities.ts

@@ -1,12 +1,27 @@
 import { ClapProject, fetchClap, serializeClap } from "@aitube/clap"
 
 import { aitubeApiUrl } from "@/config"
+import { ClapCompletionMode } from "./types"
 
 export async function editClapEntities({
   clap,
+  completionMode = ClapCompletionMode.MERGE,
   token,
 }: {
+  // A ClapProject instance
   clap: ClapProject
+
+  /**
+   * Completion mode (optional, defaults to "merge")
+   * 
+   * Possible values are:
+   * - full: the API and the client will return a full clap file. This is a very convenient and simple mode, but it is also very ineficient, so it should not be used for intensive applications.
+   * - partial: the API and the client will return a partial clap file, containing only the new values and changes. This is useful for real-time applications and streaming.
+   * - merge: the API will return a partial clap file, and the client will return a merge of the original with the new values. This is safe to run, there are no side-effects.
+   * - replace: the API will return a partial clap file, and the client will replace the original. This is the most efficient mode, but it relies on side-effects and inline object updates. 
+   */
+  completionMode?: ClapCompletionMode
+
   token?: string
 }): Promise<ClapProject> {
 
@@ -14,7 +29,16 @@ export async function editClapEntities({
   
   const hasToken = typeof token === "string" && token.length > 0
 
-  const newClap = await fetchClap(`${aitubeApiUrl}edit/entities`, {
+  const newClap = await fetchClap(
+    `${aitubeApiUrl}edit/entities${
+      typeof completionMode === "string"
+      ? `?c=${
+          completionMode === ClapCompletionMode.FULL
+          ? "full"
+          : "partial"
+        }`
+      : ""
+    }`, {
     method: "POST",
     headers: {
       "Content-Type": "application/x-gzip",

packages/aitube-client/src/api/editClapStoryboards.ts

@@ -1,12 +1,26 @@
 import { ClapProject, fetchClap, serializeClap } from "@aitube/clap"
 
 import { aitubeApiUrl } from "@/config"
+import { ClapCompletionMode } from "./types"
 
 export async function editClapStoryboards({
   clap,
+  completionMode = ClapCompletionMode.MERGE,
   token,
 }: {
   clap: ClapProject
+
+  /**
+   * Completion mode (optional, defaults to "merge")
+   * 
+   * Possible values are:
+   * - full: the API and the client will return a full clap file. This is a very convenient and simple mode, but it is also very ineficient, so it should not be used for intensive applications.
+   * - partial: the API and the client will return a partial clap file, containing only the new values and changes. This is useful for real-time applications and streaming.
+   * - merge: the API will return a partial clap file, and the client will return a merge of the original with the new values. This is safe to run, there are no side-effects.
+   * - replace: the API will return a partial clap file, and the client will replace the original. This is the most efficient mode, but it relies on side-effects and inline object updates. 
+   */
+  completionMode?: ClapCompletionMode
+
   token?: string
 }): Promise<ClapProject> {
 
@@ -14,7 +28,15 @@ export async function editClapStoryboards({
   
   const hasToken = typeof token === "string" && token.length > 0
 
-  const newClap = await fetchClap(`${aitubeApiUrl}edit/storyboards`, {
+  const newClap = await fetchClap(`${aitubeApiUrl}edit/storyboards${
+    typeof completionMode === "string"
+    ? `?c=${
+        completionMode === ClapCompletionMode.FULL
+        ? "full"
+        : "partial"
+      }`
+    : ""
+  }`, {
     method: "POST",
     headers: {
       "Content-Type": "application/x-gzip",

packages/aitube-client/src/api/editClapVideos.ts

@@ -1,12 +1,26 @@
 import { ClapProject, fetchClap, serializeClap } from "@aitube/clap"
 
 import { aitubeApiUrl } from "@/config"
+import { ClapCompletionMode } from "./types"
 
 export async function editClapVideos({
   clap,
+  completionMode = ClapCompletionMode.MERGE,
   token,
 }: {
   clap: ClapProject
+  
+  /**
+   * Completion mode (optional, defaults to "merge")
+   * 
+   * Possible values are:
+   * - full: the API and the client will return a full clap file. This is a very convenient and simple mode, but it is also very ineficient, so it should not be used for intensive applications.
+   * - partial: the API and the client will return a partial clap file, containing only the new values and changes. This is useful for real-time applications and streaming.
+   * - merge: the API will return a partial clap file, and the client will return a merge of the original with the new values. This is safe to run, there are no side-effects.
+   * - replace: the API will return a partial clap file, and the client will replace the original. This is the most efficient mode, but it relies on side-effects and inline object updates. 
+   */
+  completionMode?: ClapCompletionMode
+
   token?: string
 }): Promise<ClapProject> {
 
@@ -14,7 +28,15 @@ export async function editClapVideos({
   
   const hasToken = typeof token === "string" && token.length > 0
 
-  const newClap = await fetchClap(`${aitubeApiUrl}edit/videos`, {
+  const newClap = await fetchClap(`${aitubeApiUrl}edit/videos${
+    typeof completionMode === "string"
+    ? `?c=${
+        completionMode === ClapCompletionMode.FULL
+        ? "full"
+        : "partial"
+      }`
+    : ""
+  }`, {
     method: "POST",
     headers: {
       "Content-Type": "application/x-gzip",

packages/aitube-client/src/api/exportClapToVideo.ts

@@ -11,7 +11,14 @@ export async function exportClapToVideo({
   token,
 }: {
   clap: ClapProject
+
+  /**
+   * Desired output video format (defaults to "mp4")
+   * 
+   * Can be either "mp4" or "webm"
+   */
   format?: SupportedExportFormat
+
   token?: string
 }): Promise<string> {
   

packages/aitube-client/src/api/index.ts

@@ -3,4 +3,5 @@ export { editClapStoryboards } from "./editClapStoryboards"
 export { editClapVideos } from "./editClapVideos"
 export { editClapDialogues } from "./editClapDialogues"
 export { editClapEntities } from "./editClapEntities"
-export { createClap } from "./createClap"
+export { createClap } from "./createClap"
+export { ClapCompletionMode } from "./types"

packages/aitube-client/src/api/types.ts

@@ -0,0 +1,28 @@
+export enum ClapCompletionMode {
+  /**
+   * the API and the client will return a full clap file.
+   * This is a very convenient and simple mode, but it is also very ineficient,
+   * so it should not be used for intensive applications.
+   */
+  FULL = "full",
+
+  /**
+   * the API and the client will return a partial clap file containing only the changes,
+   * containing only the new values and changes.
+   * This is useful for real-time applications and streaming.
+   */
+  PARTIAL = "partial",
+
+  /**
+   * the API will return a partial clap file containing only the changes,
+   * and the client will return a merge of the original with the new values.
+   * This is safe to run, there are no side-effects.
+   */
+  MERGE = "merge",
+
+  /**
+   * the API will return a partial clap file, and the client will replace the original.
+   * This is the most efficient mode, but it relies on side-effects and inline object updates.
+   */
+  REPLACE = "replace"
+}

packages/aitube-client/src/index.ts

@@ -6,6 +6,7 @@ export {
   editClapStoryboards,
   editClapVideos,
   exportClapToVideo,
+  ClapCompletionMode,
 } from './api'
 
 export {