samsar-js 0.48.30 → 0.48.31

package/README.md

@@ -346,6 +346,24 @@ const images = await samsar.extendImageList({
   aspect_ratio: '16:9',
 });
 
+// Assign a short SEO-friendly image title
+const imageTitle = await samsar.assignImageTitle({
+  image_url: 'https://example.com/product-photo.png',
+  metadata: {
+    product: 'linen travel shirt',
+    collection: 'spring essentials',
+  },
+});
+console.log(imageTitle.data.content); // "Linen Travel Shirt"
+
+// Binary uploads are also supported in browser/Node 18+ runtimes
+const fileTitle = await samsar.assignImageTitle({
+  image: fileOrBlob,
+  fileName: 'product-photo.png',
+  mimeType: 'image/png',
+  metadata: { product: 'linen travel shirt' },
+});
+
 // Create a reusable receipt template from one sample receipt image (free endpoint)
 const receiptTemplate = await samsar.createReceiptTemplate({
   image_url: 'https://example.com/receipt-template.png',
@@ -579,7 +597,7 @@ Video model support notes:
 
 Upcoming `/v2` omni route adapters:
 - `/v2` is additive; `/v1` is not deprecated.
-- `createV2VideoFromText`, `createV2VideoFromImageList`, `translateV2Video`, `cloneV2Video`, `regenerateV2VideoAvatar`, `updateV2VideoOutroImage`, `updateV2VideoFooterImage`, `addV2VideoOutroImage`, `getV2Status`, `getV2StatusDetailed`, `getV2Credits`, `listV2Requests`, and `createV2Session` call the new omni route surface.
+- `createV2VideoFromText`, `createV2VideoFromImageList`, `assignV2ImageTitle`, `translateV2Video`, `cloneV2Video`, `regenerateV2VideoAvatar`, `updateV2VideoOutroImage`, `updateV2VideoFooterImage`, `addV2VideoOutroImage`, `getV2Status`, `getV2StatusDetailed`, `getV2Credits`, `listV2Requests`, and `createV2Session` call the new omni route surface.
 - Step-controlled video helpers include `createV2StepVideoFromText`, `createV2StepTextToVideo`, `createV2StepVideoFromImage`, `createV2StepImageToVideo`, `getV2StepVideoStatus`, `getV2StepVideoStatusDetailed`, and `processNextV2StepVideo`. They default to 1-step express rendering by sending `auto_render_full_video: true` and `manual_step_stages: []`; pass `{ stepMode: 'two_step' }` or `manual_step_stages: ['ai_video_generation']` to require an explicit second-step approval before image-to-video generation.
 - Programmatic user helpers include `createV2ExternalUser`, `createV2UserRechargeCredits`, `refreshV2UserToken`, `createV2UserAppKey`, `refreshV2UserAppKey`, `getV2UserCredits`, `getV2UserUsageLogs`, and `getV2UserPaymentStatus`.
 - Omit `externalUser` for internal account billing, pass `externalUser` to scope an external user with the account API key, or authenticate the client directly with an external-user auth token/API key. V2 external users can be referenced by `unique_key`; if `unique_key` is omitted during creation, the server uses `external_user_id` as the key.
@@ -601,6 +619,12 @@ const v2ExternalVideo = await platform.createV2VideoFromImageList(
   { externalUser },
 );
 
+const v2ImageTitle = await platform.assignV2ImageTitle({
+  image_url: 'https://cdn.example.com/product-frame.png',
+  metadata: { product: 'travel shirt', channel: 'marketplace' },
+});
+console.log(v2ImageTitle.data.content);
+
 const v2Translated = await platform.translateV2Video({
   videoSessionId: v2Video.data.request_id!,
   language: 'es',

package/dist/index.d.ts

@@ -975,6 +975,33 @@ export interface EnhanceImageResponse {
     remainingCredits?: number;
     [key: string]: unknown;
 }
+export type AssignImageTitleMimeType = 'image/png' | 'image/jpeg' | 'image/webp' | 'image/gif';
+export type AssignImageTitleBinaryInput = Blob | ArrayBuffer | Uint8Array;
+export interface AssignImageTitleRequest {
+    image?: string | AssignImageTitleBinaryInput;
+    file?: AssignImageTitleBinaryInput;
+    image_file?: AssignImageTitleBinaryInput;
+    imageFile?: AssignImageTitleBinaryInput;
+    image_url?: string;
+    imageUrl?: string;
+    url?: string;
+    image_data?: string;
+    imageData?: string;
+    image_data_url?: string;
+    imageDataUrl?: string;
+    metadata?: Record<string, unknown> | string;
+    metadata_json?: Record<string, unknown> | string;
+    metadataJson?: Record<string, unknown> | string;
+    fileName?: string;
+    filename?: string;
+    mimeType?: AssignImageTitleMimeType | string;
+    [key: string]: unknown;
+}
+export interface AssignImageTitleResponse {
+    content: string;
+    title?: string;
+    [key: string]: unknown;
+}
 export interface ExtendImageListRequest {
     image_urls: string[];
     num_images: number;
@@ -1978,6 +2005,12 @@ export declare class SamsarClient {
     uploadV2ImageData(imageData: string[], options?: V2RequestOptions): Promise<SamsarResult<{
         image_urls: string[];
     }>>;
+    /**
+     * Assign a short SEO-friendly title to an image using the /v2 image route.
+     * Supports image_url/image_data JSON payloads or binary image/FormData uploads.
+     */
+    assignV2ImageTitle(payload: AssignImageTitleRequest | FormData, options?: V2RequestOptions): Promise<SamsarResult<AssignImageTitleResponse>>;
+    assignV2TitleToImage(payload: AssignImageTitleRequest | FormData, options?: V2RequestOptions): Promise<SamsarResult<AssignImageTitleResponse>>;
     updateV2VideoOutroImage(input: UpdateVideoOutroImageInput, options?: V2RequestOptions): Promise<SamsarResult<UpdateVideoOutroImageResponse | ExternalRequestResponse>>;
     updateV2VideoFooterImage(input: UpdateVideoFooterImageInput, options?: V2RequestOptions): Promise<SamsarResult<UpdateVideoFooterImageResponse | ExternalRequestResponse>>;
     addV2VideoOutroImage(input: AddVideoOutroImageInput, options?: V2RequestOptions): Promise<SamsarResult<AddVideoOutroImageResponse | ExternalRequestResponse>>;
@@ -2263,6 +2296,12 @@ export declare class SamsarClient {
      * Enhance an image by upscaling it with the specified resolution.
      */
     enhanceImage(payload: EnhanceImageRequest, options?: SamsarRequestOptions): Promise<SamsarResult<EnhanceImageResponse>>;
+    /**
+     * Assign a short SEO-friendly title to an image.
+     * Supports image_url/image_data JSON payloads or binary image/FormData uploads.
+     */
+    assignImageTitle(payload: AssignImageTitleRequest | FormData, options?: SamsarRequestOptions): Promise<SamsarResult<AssignImageTitleResponse>>;
+    assignTitleToImage(payload: AssignImageTitleRequest | FormData, options?: SamsarRequestOptions): Promise<SamsarResult<AssignImageTitleResponse>>;
     /**
      * Add or extend a saved image list for the authenticated API key.
      */
@@ -2379,6 +2418,7 @@ export declare class SamsarClient {
     }): Promise<SamsarResult<GlobalStatusResponse>>;
     private get;
     private post;
+    private postForm;
     private request;
     private buildHeaders;
     private buildUrl;

package/dist/index.js

@@ -792,6 +792,22 @@ export class SamsarClient {
             },
         }, options);
     }
+    /**
+     * Assign a short SEO-friendly title to an image using the /v2 image route.
+     * Supports image_url/image_data JSON payloads or binary image/FormData uploads.
+     */
+    async assignV2ImageTitle(payload, options) {
+        const body = buildAssignImageTitleBody(payload);
+        if (isFormDataBody(body)) {
+            return this.postForm(this.buildV2Url('image/assign_title'), body, options);
+        }
+        return this.postV2('image/assign_title', {
+            input: body,
+        }, options);
+    }
+    async assignV2TitleToImage(payload, options) {
+        return this.assignV2ImageTitle(payload, options);
+    }
     async updateV2VideoOutroImage(input, options) {
         const normalizedInput = normalizeUpdateVideoOutroImageInput(input, 'updateV2VideoOutroImage');
         return this.postV2('update_outro_image', {
@@ -1758,6 +1774,20 @@ export class SamsarClient {
     async enhanceImage(payload, options) {
         return this.post('image/enhance', payload, options);
     }
+    /**
+     * Assign a short SEO-friendly title to an image.
+     * Supports image_url/image_data JSON payloads or binary image/FormData uploads.
+     */
+    async assignImageTitle(payload, options) {
+        const body = buildAssignImageTitleBody(payload);
+        if (isFormDataBody(body)) {
+            return this.postForm('image/assign_title', body, options);
+        }
+        return this.post('image/assign_title', body, options);
+    }
+    async assignTitleToImage(payload, options) {
+        return this.assignImageTitle(payload, options);
+    }
     /**
      * Add or extend a saved image list for the authenticated API key.
      */
@@ -2132,6 +2162,13 @@ export class SamsarClient {
             body: JSON.stringify(body),
         });
     }
+    async postForm(path, body, options) {
+        return this.request(path, {
+            ...(options ?? {}),
+            method: 'POST',
+            body,
+        });
+    }
     async request(path, options) {
         const url = this.buildUrl(path, options.query);
         const controller = new AbortController();
@@ -2221,7 +2258,7 @@ export class SamsarClient {
                 : this.apiKey
                     ? `Bearer ${this.apiKey}`
                     : undefined,
-            'Content-Type': options.body ? 'application/json' : undefined,
+            'Content-Type': options.body && !isFormDataBody(options.body) ? 'application/json' : undefined,
             'x-external-user-api-key': options.externalUserApiKey ?? this.externalUserApiKey,
             'x-app-secret': resolvedAppKey ? resolvedAppSecret : undefined,
             ...this.defaultHeaders,
@@ -2288,6 +2325,104 @@ export class SamsarClient {
 function trimTrailingSlash(url) {
     return url.replace(/\/+$/, '');
 }
+function buildAssignImageTitleBody(payload) {
+    if (isFormDataBody(payload)) {
+        return payload;
+    }
+    const input = (payload ?? {});
+    const image = input.image ??
+        input.file ??
+        input.image_file ??
+        input.imageFile;
+    if (isBinaryAssignImageTitleInput(image)) {
+        return buildAssignImageTitleFormData(input, image);
+    }
+    const stringImage = getTrimmedString(image);
+    const imageData = stringImage?.startsWith('data:image/')
+        ? stringImage
+        : getTrimmedString(input.image_data) ??
+            getTrimmedString(input.imageData) ??
+            getTrimmedString(input.image_data_url) ??
+            getTrimmedString(input.imageDataUrl);
+    const imageUrl = stringImage && !stringImage.startsWith('data:image/')
+        ? stringImage
+        : getTrimmedString(input.image_url) ??
+            getTrimmedString(input.imageUrl) ??
+            getTrimmedString(input.url);
+    const metadata = input.metadata ?? input.metadata_json ?? input.metadataJson;
+    if (!imageData && !imageUrl) {
+        throw new Error('image, image_data, or image_url is required for assignImageTitle');
+    }
+    return {
+        ...(imageData ? { image_data: imageData } : {}),
+        ...(imageUrl ? { image_url: imageUrl } : {}),
+        ...(metadata !== undefined ? { metadata } : {}),
+    };
+}
+function buildAssignImageTitleFormData(input, image) {
+    if (typeof FormData === 'undefined') {
+        throw new Error('FormData is required for binary assignImageTitle uploads');
+    }
+    const metadata = input.metadata ?? input.metadata_json ?? input.metadataJson;
+    const mimeType = getTrimmedString(input.mimeType) ?? getBlobType(image);
+    if (!mimeType || !isSupportedAssignImageTitleMimeType(mimeType)) {
+        throw new Error('mimeType must be image/png, image/jpeg, image/webp, or image/gif for binary assignImageTitle uploads');
+    }
+    const blob = toAssignImageTitleBlob(image, mimeType);
+    const fileName = getTrimmedString(input.fileName) ??
+        getTrimmedString(input.filename) ??
+        `image.${mimeTypeToExtension(mimeType)}`;
+    const formData = new FormData();
+    formData.append('image', blob, fileName);
+    if (metadata !== undefined) {
+        formData.append('metadata', typeof metadata === 'string' ? metadata : JSON.stringify(metadata));
+    }
+    return formData;
+}
+function isBinaryAssignImageTitleInput(value) {
+    return (isBlobValue(value) ||
+        value instanceof ArrayBuffer ||
+        value instanceof Uint8Array);
+}
+function toAssignImageTitleBlob(value, mimeType) {
+    if (isBlobValue(value)) {
+        if (value.type === mimeType) {
+            return value;
+        }
+        return new Blob([value], { type: mimeType });
+    }
+    if (value instanceof Uint8Array) {
+        const arrayBuffer = value.buffer.slice(value.byteOffset, value.byteOffset + value.byteLength);
+        return new Blob([arrayBuffer], { type: mimeType });
+    }
+    return new Blob([value], { type: mimeType });
+}
+function getBlobType(value) {
+    return isBlobValue(value) ? getTrimmedString(value.type) : undefined;
+}
+function isBlobValue(value) {
+    return typeof Blob !== 'undefined' && value instanceof Blob;
+}
+function isFormDataBody(body) {
+    return typeof FormData !== 'undefined' && body instanceof FormData;
+}
+function isSupportedAssignImageTitleMimeType(value) {
+    const normalized = value.trim().toLowerCase();
+    return ['image/png', 'image/jpeg', 'image/jpg', 'image/webp', 'image/gif'].includes(normalized);
+}
+function mimeTypeToExtension(value) {
+    const normalized = value.trim().toLowerCase();
+    if (normalized === 'image/jpeg' || normalized === 'image/jpg') {
+        return 'jpg';
+    }
+    if (normalized === 'image/webp') {
+        return 'webp';
+    }
+    if (normalized === 'image/gif') {
+        return 'gif';
+    }
+    return 'png';
+}
 function parseMaybeJson(value) {
     try {
         return JSON.parse(value);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "samsar-js",
-  "version": "0.48.30",
+  "version": "0.48.31",
   "description": "TypeScript client for the Samsar Processor API routes.",
   "type": "module",
   "main": "dist/index.js",