Merge pull request #51 from cosmicjs/tony/ai

add: AI endpoints

Author: tonyspiro

.changeset/seven-brooms-sip.md

@@ -0,0 +1,5 @@
+---
+'@cosmicjs/sdk': minor
+---
+
+Adds AI methods: generateText and generateImage

README.md

@@ -121,6 +121,82 @@ Use the `objects.deleteOne()` method to delete an Object by specifying the Objec
 await cosmic.objects.deleteOne('5ff75368c2dfa81a91695cec');
 ```
 
+## AI Capabilities
+
+Cosmic provides AI-powered text and image generation capabilities through the SDK.
+
+### Generate Text [[see docs](https://www.cosmicjs.com/docs/api/ai#generate-text)]
+
+Use the `ai.generateText()` method to generate text content using AI models. You must provide either a `prompt` or `messages` parameter.
+
+#### Using a simple prompt:
+
+```jsx
+const textResponse = await cosmic.ai.generateText({
+  prompt: 'Write a product description for a coffee mug',
+  max_tokens: 500, // optional
+});
+
+console.log(textResponse.text);
+console.log(textResponse.usage); // { input_tokens: 10, output_tokens: 150 }
+```
+
+#### Using messages for chat-based models:
+
+```jsx
+const chatResponse = await cosmic.ai.generateText({
+  messages: [
+    { role: 'user', content: 'Tell me about coffee mugs' },
+    {
+      role: 'assistant',
+      content: 'Coffee mugs are vessels designed to hold hot beverages...',
+    },
+    { role: 'user', content: 'What materials are they typically made from?' },
+  ],
+  max_tokens: 500, // optional
+});
+
+console.log(chatResponse.text);
+console.log(chatResponse.usage);
+```
+
+### Analyze Images and Files
+
+The AI model can analyze images and files when generating text responses. This feature works with both the `prompt` and `messages` approaches.
+
+```jsx
+const textWithImageResponse = await cosmic.ai.generateText({
+  prompt: 'Describe this coffee mug and suggest improvements to its design',
+  media_url: 'https://imgix.cosmicjs.com/your-image-url.jpg',
+  max_tokens: 500,
+});
+
+console.log(textWithImageResponse.text);
+console.log(textWithImageResponse.usage);
+```
+
+### Generate Image [[see docs](https://www.cosmicjs.com/docs/api/ai#generate-image)]
+
+Use the `ai.generateImage()` method to create AI-generated images based on text prompts.
+
+```jsx
+const imageResponse = await cosmic.ai.generateImage({
+  prompt: 'A serene mountain landscape at sunset',
+  // Optional parameters
+  metadata: { tags: ['landscape', 'mountains', 'sunset'] },
+  folder: 'ai-generated-images',
+  alt_text: 'A beautiful mountain landscape with a colorful sunset',
+});
+
+// Access the generated image properties
+console.log(imageResponse.media.url); // Direct URL to the generated image
+console.log(imageResponse.media.imgix_url); // Imgix-enhanced URL for additional transformations
+console.log(imageResponse.media.width); // Image width
+console.log(imageResponse.media.height); // Image height
+console.log(imageResponse.media.alt_text); // Alt text for the image
+console.log(imageResponse.revised_prompt); // Potentially revised prompt used by the AI
+```
+
 ## Learn more
 
 Go to the [Cosmic docs](https://www.cosmicjs.com/docs) to learn more capabilities.

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicjs/sdk",
-  "version": "1.3.2",
+  "version": "1.3.4",
   "description": "The official client module for Cosmic. This module helps you easily add dynamic content to your website or application using the Cosmic headless CMS.",
   "keywords": [
     "headlesscms",
@@ -63,4 +63,4 @@
       "npx eslint --fix"
     ]
   }
-}
+}

src/clients/bucket/ai/index.ts

@@ -0,0 +1,88 @@
+import { BucketConfig, APIConfig } from '../../../types/config.types';
+import { requestHandler } from '../../../utils/request.handler';
+
+export interface GenerateTextOptions {
+  prompt?: string;
+  media_url?: string;
+  model?: string;
+  max_tokens?: number;
+  stream?: boolean;
+  messages?: Array<{
+    role: 'user' | 'assistant';
+    content: string;
+  }>;
+}
+
+export interface GenerateImageOptions {
+  prompt: string;
+  model?: string;
+  metadata?: Record<string, any>;
+  folder?: string;
+  alt_text?: string;
+}
+
+export interface TextGenerationResponse {
+  text: string;
+  usage: {
+    input_tokens: number;
+    output_tokens: number;
+  };
+}
+
+export interface ImageGenerationResponse {
+  media: {
+    id: string;
+    name: string;
+    original_name: string;
+    size: number;
+    type: string;
+    bucket: string;
+    created_at: string;
+    created_by: string | null;
+    modified_at: string;
+    modified_by: string | null;
+    width: number;
+    height: number;
+    alt_text?: string;
+    url: string;
+    imgix_url: string;
+    metadata?: Record<string, any>;
+    folder?: string | null;
+  };
+  revised_prompt: string;
+}
+
+export const aiChainMethods = (
+  bucketConfig: BucketConfig,
+  apiConfig: APIConfig
+) => {
+  const { uploadUrl } = apiConfig;
+  const { bucketSlug, writeKey } = bucketConfig;
+
+  const headers: Record<string, string> = {
+    'Content-Type': 'application/json',
+  };
+
+  if (writeKey) {
+    headers.Authorization = `Bearer ${writeKey}`;
+  }
+
+  return {
+    generateText: async (
+      options: GenerateTextOptions
+    ): Promise<TextGenerationResponse> => {
+      if (!options.prompt && !options.messages) {
+        throw new Error('Either prompt or messages must be provided');
+      }
+      const endpoint = `${uploadUrl}/buckets/${bucketSlug}/ai/text`;
+      return requestHandler('POST', endpoint, options, headers);
+    },
+
+    generateImage: async (
+      options: GenerateImageOptions
+    ): Promise<ImageGenerationResponse> => {
+      const endpoint = `${uploadUrl}/buckets/${bucketSlug}/ai/image`;
+      return requestHandler('POST', endpoint, options, headers);
+    },
+  };
+};

src/clients/bucket/index.ts

@@ -4,6 +4,21 @@ import { mediaChainMethods } from './media';
 import { objectsChainMethods } from './objects';
 import { objectTypesChainMethods } from './objectTypes';
 import { objectRevisionsChainMethods } from './objectRevisions';
+import { aiChainMethods } from './ai';
+import type {
+  GenerateTextOptions,
+  TextGenerationResponse,
+  GenerateImageOptions,
+  ImageGenerationResponse,
+} from './ai';
+
+// Re-export the types
+export type {
+  GenerateTextOptions,
+  TextGenerationResponse,
+  GenerateImageOptions,
+  ImageGenerationResponse,
+};
 
 export const createBucketClient = (config: BucketConfig) => {
   const bucketConfig: BucketConfig = {
@@ -18,6 +33,7 @@ export const createBucketClient = (config: BucketConfig) => {
     objectTypes: objectTypesChainMethods(bucketConfig, apiConfig),
     objectRevisions: objectRevisionsChainMethods(bucketConfig, apiConfig),
     media: mediaChainMethods(bucketConfig, apiConfig),
+    ai: aiChainMethods(bucketConfig, apiConfig),
   };
 };