@websimai/client-api-types 0.0.1 → 0.0.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@websimai/client-api-types",
-  "version": "0.0.1",
+  "version": "0.0.2",
   "description": "Type declarations for `window.websim` object",
   "author": "GameRoMan",
   "license": "MIT",
@@ -8,9 +8,6 @@
   "exports": {
     ".": {
       "types": "./src/index.d.ts"
-    },
-    "./client": {
-      "types": "./src/client.d.ts"
     }
   },
   "scripts": {

package/src/client-api.d.ts

@@ -0,0 +1,74 @@
+import type { WebsimUser, WebsimUserOrAnonymous } from "./types";
+
+import type { ChatCompletionOptions, ChatCompletionResult } from "./types";
+
+import type { ImageGenOptions, ImageGenResult } from "./types";
+
+import type { TextToSpeechOptions, TextToSpeechResult } from "./types";
+
+export interface WebsimClientAPI {
+  getUser(): Promise<WebsimUserOrAnonymous>;
+  /** Alias for getUser */
+  getCurrentUser(): Promise<WebsimUserOrAnonymous>;
+  /** @deprecated Use getBootstrap instead */
+  getDistinctId(): Promise<string>;
+  getBootstrap(): Promise<{
+    readonly distinct_id: string;
+    readonly session_id: string;
+  }>;
+  getCreatedBy(): Promise<WebsimUser>;
+  /** Alias for getCreatedBy */
+  getCreator(): Promise<WebsimUser>;
+  getCurrentProject(): Promise<{
+    readonly id: string;
+    readonly title: string;
+    readonly description: string;
+  }>;
+  getColorScheme(): Promise<"light" | "dark">;
+
+  postComment(args: {
+    content: string;
+    credits?: number;
+    images?: string[];
+  }): Promise<{ readonly error?: "User has not interacted with the page" }>;
+
+  addEventListener(
+    eventType: "comment:created",
+    callback: (data: any) => void
+  ): () => void;
+
+  upload: (file: File) => Promise<string>;
+
+  readonly chat: {
+    readonly completions: {
+      create: (args: ChatCompletionOptions) => Promise<ChatCompletionResult>;
+    };
+  };
+
+  imageGen: (args: ImageGenOptions) => Promise<ImageGenResult>;
+
+  textToSpeech: (args: TextToSpeechOptions) => Promise<TextToSpeechResult>;
+
+  experimental: {
+    v0: {
+      login: () => Promise<void>;
+
+      /**
+       * Saves the given htmlContent to a new websim site.
+       * @param htmlContent html content to save
+       * @returns object with id of the saved site
+       */
+      save(htmlContent: string): Promise<{ id: string }>;
+
+      /**
+       * Returns the HTML for the given siteId.
+       * Defaults to the current websimsite.
+       * @param siteId
+       * @returns HTML for the given siteId.
+       */
+      getHTML(siteId?: string): Promise<string>;
+    };
+  };
+
+  internal_only_experimental: {};
+}

package/src/globals.d.ts

@@ -0,0 +1,9 @@
+import type { WebsimClientAPI } from "./client-api";
+
+declare global {
+  interface Window {
+    readonly websim: WebsimClientAPI;
+  }
+
+  declare const websim: WebsimClientAPI;
+}

package/src/index.d.ts

@@ -1,9 +1,4 @@
-import type { WebsimClientAPI } from "./client";
+export type { WebsimClientAPI } from "./client-api";
+export type * from "./types";
 
-declare global {
-  interface Window {
-    readonly websim: WebsimClientAPI;
-  }
-
-  declare const websim: WebsimClientAPI;
-}
+export type * from "./globals";

package/src/types/chat.d.ts

@@ -0,0 +1,106 @@
+export type ChatCompletionsMessageRole =
+  | "system"
+  | "user"
+  | "assistant"
+  | "tool";
+
+export type ChatCompletionsMessageContent =
+  | {
+      /**
+       * The type of content part.
+       */
+      type: "text";
+      /**
+       * The text content.
+       */
+      text: string;
+    }
+  | {
+      /**
+       * The type of content part.
+       */
+      type: "image_url";
+      /**
+       * An object containing the base64 encoded image data URL.
+       */
+      image_url: {
+        /**
+         * A base64 encoded image data URL.
+         */
+        url: string;
+      };
+    };
+
+/**
+ * Represents a single message in the conversation history.
+ */
+export type ChatCompletionsMessage = {
+  /**
+   * The role of the message sender.
+   */
+  role: ChatCompletionsMessageRole;
+  /**
+   * The message content.
+   * Can be plain text or an array for multimodal inputs.
+   */
+  content: string | ChatCompletionsMessageContent[];
+};
+
+export type ChatCompletionOptions = {
+  /**
+   * A list of messages comprising the conversation so far.
+   * Each message includes a `role` (system, user, assistant, tool) and `content`.
+   */
+  messages: ChatCompletionsMessage[];
+  /**
+   * ID of the model to use.
+   * If not specified, websim uses its default model.
+   */
+  model?: string;
+  /**
+   * If `true`, the model will attempt to generate a JSON object.
+   * The response content will be a string that you will need to parse.
+   * Defaults to `false`.
+   */
+  json?: boolean;
+  /**
+   * If `true`, the response will be streamed back incrementally.
+   * Defaults to `false`.
+   */
+  stream?: boolean;
+  /**
+   * What sampling temperature to use, between 0 and 2.
+   * Higher values (e.g., 0.8) make the output more random; lower values (e.g., 0.2) make it more focused.
+   * Defaults to 1.
+   */
+  temperature?: number;
+  /**
+   * An alternative to sampling with temperature, where the model considers tokens with top_p probability mass.
+   * E.g., 0.1 means only tokens comprising the top 10% probability mass are considered.
+   * Defaults to 1.
+   */
+  top_p?: number;
+  /**
+   * The maximum number of tokens to generate in the chat completion.
+   */
+  max_tokens?: number;
+};
+
+export type ChatCompletionResult = {
+  /**
+   * The generated text content from the assistant.
+   */
+  readonly content: string;
+  /**
+   * The role of the message sender, which will always be "assistant" for the model's response.
+   */
+  readonly role: "assistant";
+};
+
+export namespace ChatCompletions {
+  export type MessageRole = ChatCompletionsMessageRole;
+  export type ContentPart = ChatCompletionsMessageContent;
+  export type Message = ChatCompletionsMessage;
+  export type Options = ChatCompletionOptions;
+  export type Result = ChatCompletionResult;
+}

package/src/types/image-gen.d.ts

@@ -0,0 +1,67 @@
+export type ImageGenAspectRatio =
+  | "1:1"
+  | "16:9"
+  | "21:9"
+  | "3:2"
+  | "2:3"
+  | "4:5"
+  | "5:4"
+  | "3:4"
+  | "4:3"
+  | "9:16"
+  | "9:21";
+
+export type ImageGenOptions = {
+  /**
+   * The primary text prompt describing the image to generate.
+   * This is a required parameter.
+   */
+  prompt: string;
+  /**
+   * Optional aspect ratio for the generated image.
+   * Defaults to "1:1".
+   * If `width` and `height` are provided, this parameter will be ignored.
+   */
+  aspect_ratio?: ImageGenAspectRatio;
+  /**
+   * Optional width of the generated image in pixels.
+   * If provided along with `height`, it overrides `aspect_ratio`.
+   */
+  width?: number;
+  /**
+   * Optional height of the generated image in pixels.
+   * If provided along with `width`, it overrides `aspect_ratio`.
+   */
+  height?: number;
+  /**
+   * Optional boolean.
+   * If `true`, the generated image will have a transparent background.
+   * Defaults to `false`.
+   */
+  transparent?: boolean;
+  /**
+   * Optional array of image inputs.
+   * Each object in the array should have a `url` property, which is a base64 encoded image data URL.
+   * Supports 1-4 input images for image-to-image generation.
+   */
+  image_inputs?: { url: string }[];
+  /**
+   * Optional seed for the image generation process.
+   * Using the same prompt and seed will produce variations of the same output, useful for consistent results or exploring variations.
+   */
+  seed?: number;
+};
+
+export type ImageGenResult = {
+  /**
+   * The URL of the generated image.
+   * This URL can be used to display the image.
+   */
+  readonly url: `https://${string}/${string}`;
+};
+
+export namespace ImageGen {
+  export type AspectRatio = ImageGenAspectRatio;
+  export type Options = ImageGenOptions;
+  export type Result = ImageGenResult;
+}

package/src/types/index.d.ts

@@ -0,0 +1,4 @@
+export type * from "./chat";
+export type * from "./image-gen";
+export type * from "./user";
+export type * from "./text-to-speech";

package/src/types/text-to-speech.d.ts

@@ -0,0 +1,32 @@
+export type TextToSpeechOptions = {
+  /**
+   * The text string to synthesize to speech.
+   */
+  text: string;
+  /**
+   * Voice identifier (e.g., "en-male") or ElevenLabs voice ID for a specific voice.
+   */
+  voice?: string;
+  /**
+   * Desired audio format.
+   * Defaults to "mp3".
+   */
+  format?: "mp3" | "wav";
+  /**
+   * Playback speed multiplier.
+   * Typical range 0.5 - 2.0.
+   */
+  speed?: number;
+  /**
+   * Pitch adjustment in semitones.
+   * Typical range -12 to 12.
+   */
+  pitch?: number;
+};
+
+export type TextToSpeechResult = {
+  /**
+   * A public URL pointing to the generated audio file.
+   */
+  readonly url: `https://${string}/${string}`;
+};

package/src/types/user.d.ts

@@ -0,0 +1,13 @@
+export type AnonymousWebsimUser = {
+  readonly id: "1";
+  readonly username: "anonymous";
+  readonly avatar_url: null;
+};
+
+export type WebsimUser = {
+  readonly id: string;
+  readonly username: string;
+  readonly avatar_url: `https://${string}/${string}` | null;
+};
+
+export type WebsimUserOrAnonymous = WebsimUser | AnonymousWebsimUser;

package/src/client.d.ts

@@ -1,106 +0,0 @@
-export type ChatCompletionsMessageContent =
-  | { type: "text"; text: string }
-  | { type: "image_url"; image_url: { url: string } };
-
-export type ChatCompletionsMessage = {
-  role: "assistant" | "user" | "system";
-  content: string | ChatCompletionsMessageContent[];
-};
-
-export type AnonymousWebsimUser = {
-  id: "1";
-  username: "anonymous";
-  avatar_url: null;
-};
-
-export type WebsimUser = {
-  id: string;
-  username: string;
-  avatar_url: `https://${string}/${string}` | null;
-};
-
-export type WebsimUserOrAnonymous = WebsimUser | AnonymousWebsimUser;
-
-export interface WebsimClientAPI {
-  getUser(): Promise<WebsimUserOrAnonymous>;
-  /** Alias for getUser */
-  getCurrentUser(): Promise<WebsimUserOrAnonymous>;
-  /** @deprecated Use getBootstrap instead */
-  getDistinctId(): Promise<string>;
-  getBootstrap(): Promise<{
-    distinct_id: string;
-    session_id: string;
-  }>;
-  getCreatedBy(): Promise<WebsimUser>;
-  getCreator(): Promise<WebsimUser>;
-  getCurrentProject(): Promise<{
-    id: string;
-    title: string;
-    description: string;
-  }>;
-  getColorScheme(): Promise<"light" | "dark">;
-
-  postComment({
-    content,
-    credits,
-  }: {
-    content: string;
-    credits: number;
-  }): Promise<{} | { error: "User has not interacted with the page" }>;
-
-  addEventListener(
-    eventType: "comment:created",
-    callback: (data: any) => void
-  ): () => void;
-
-  upload: (file: File) => Promise<string>;
-
-  chat: {
-    completions: {
-      create: ({
-        messages,
-        json,
-      }: {
-        messages: ChatCompletionsMessage[];
-        json?: boolean;
-      }) => Promise<{ role: "assistant"; content: string }>;
-    };
-  };
-
-  imageGen: (args: {
-    prompt: string;
-    aspect_ratio?: string;
-    width?: number;
-    height?: number;
-    seed?: number;
-    transparent?: boolean;
-  }) => Promise<{ url: string }>;
-
-  textToSpeech: (args: {
-    text: string;
-    voice?: string;
-    voice_sample?: string;
-  }) => Promise<{ url: string }>;
-
-  experimental: {
-    v0: {
-      login: () => Promise<void>;
-
-      /**
-       * Saves the given htmlContent to a new websim site.
-       * @param htmlContent html content to save
-       * @returns object with id of the saved site
-       */
-      save(htmlContent: string): Promise<{ id: string }>;
-
-      /**
-       * Returns the HTML for the given siteId. Defaults to the current websimsite.
-       * @param siteId
-       * @returns HTML for the given siteId.
-       */
-      getHTML(siteId?: string): Promise<string>;
-    };
-  };
-
-  internal_only_experimental: {};
-}