samsar-js 0.48.18 → 0.48.20

package/README.md

@@ -423,6 +423,20 @@ const externalRender = await platform.createExternalVideoFromText(externalUser,
   enable_subtitles: true,
 });
 
+// Update an external user's existing outro by generating a new QR CTA outro
+const externalOutroUpdate = await platform.updateExternalVideoOutroImage(externalUser, {
+  request_id: externalRender.data.request_id,
+  generate_outro_image: true,
+  cta_url: 'https://example.com/shop',
+  cta_text_top: 'Scan to shop',
+  cta_text_bottom: 'Limited drop',
+  add_outro_animation: true,
+});
+console.log(externalOutroUpdate.data.request_id);
+
+// Repeated video routes accept the returned extreq_ id or the normalized external id.
+// The API resolves ownership through external request mappings and GlobalSession records.
+
 // Run an assistant completion against one of that external user's sessions.
 // Credits are deducted from the external user, while the owning Samsar account model config is used internally.
 const externalAssistant = await platform.createExternalAssistantCompletion(
@@ -491,9 +505,57 @@ Video model support notes:
 - `createVideoFromImageList` accepts either a provided outro (`outro_image_url`) or server-generated QR outro (`generate_outro_image: true` with `cta_url`). Do not combine the two modes in a single request.
 - `createVideoFromImageList` can render per-scene footer QR cards by setting `add_footer_animation: true` and providing one `footer_metadata` item per image scene.
 - `updateVideoOutroImage` accepts either a replacement outro image URL (`outro_image_url`, `outroImageUrl`, `new_outro_image_url`) or a generated QR CTA outro (`generate_outro_image: true` with `cta_url`, or just `cta_url` when no outro image URL is supplied). Generated outro updates reuse the existing session image layers for tiling and only queue frame/video regeneration.
+- Main video methods and external-user methods accept the same generated outro and footer parameters. The API can resolve either internal session ids or external `extreq_...` ids on repeated video routes, so client code can keep using `translateVideo`, `joinVideos`, `addVideoOutroImage`, and `updateVideoOutroImage`; the explicit external variants are available when you want to call `/external_users/*` directly. Do not strip the `extreq_` prefix.
 - `publishPublication`, `editPublication`, and `revokePublication` manage public feed publications for completed sessions through free `/publications/*` endpoints. They work with account API keys, customer sub-account API keys, and client auth tokens when the session belongs to the authenticated actor.
 - Image-list video pricing is per rendered second: `VEO3.1I2V` and `SEEDANCEI2V` are 75 credits/sec, `KLING3.0` is 50 credits/sec, and `RUNWAYML` is 25 credits/sec.
 
+Upcoming `/v2` omni route adapters:
+- `/v2` is additive; `/v1` is not deprecated.
+- `createV2VideoFromText`, `createV2VideoFromImageList`, `updateV2VideoOutroImage`, `addV2VideoOutroImage`, `getV2Status`, `getV2Credits`, `listV2Requests`, and `createV2Session` call the new omni route surface.
+- Programmatic user billing helpers include `createV2UserRechargeCredits`, `refreshV2UserToken`, `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.
+
+```ts
+const v2Video = await platform.createV2VideoFromImageList({
+  image_urls: ['https://cdn.example.com/a.png', 'https://cdn.example.com/b.png'],
+  video_model: 'RUNWAYML',
+  generate_outro_image: true,
+  cta_url: 'https://example.com/book',
+  cta_text_top: 'Scan to book',
+});
+
+const v2ExternalVideo = await platform.createV2VideoFromImageList(
+  {
+    image_urls: ['https://cdn.example.com/a.png', 'https://cdn.example.com/b.png'],
+    video_model: 'KLING3.0',
+  },
+  { externalUser },
+);
+
+const v2Status = await platform.getV2Status(v2Video.data.request_id!);
+console.log(v2Status.data.status);
+```
+
+Programmatic user recharge and OAuth-style refresh token rotation:
+
+```ts
+const publicClient = new SamsarClient({});
+
+const checkout = await publicClient.createV2UserRechargeCredits({
+  amount: 25,
+  email: 'customer@example.com',
+  redirect_url: 'https://example.com/samsar/callback',
+});
+
+// After the Stripe webhook calls your redirect_url with authToken, refreshToken, and expiryDate:
+const userClient = new SamsarClient({ apiKey: authToken });
+const refreshed = await userClient.refreshV2UserToken(refreshToken);
+
+localStorage.setItem('authToken', refreshed.data.authToken);
+localStorage.setItem('refreshToken', refreshed.data.refreshToken);
+localStorage.setItem('expiryDate', refreshed.data.expiryDate);
+```
+
 Each method returns `{ data, status, headers, creditsCharged, creditsRemaining, raw }`. Non-2xx responses throw `SamsarRequestError` containing status, body, and credit headers (if present).
 
 ## Billing notes

package/dist/index.d.ts

@@ -2,7 +2,7 @@ type FetchLike = (input: RequestInfo | URL, init?: RequestInit) => Promise<Respo
 type QueryValue = string | number | boolean | null | undefined;
 type QueryParams = Record<string, QueryValue>;
 export interface SamsarClientOptions {
-    apiKey: string;
+    apiKey?: string;
     baseUrl?: string;
     timeoutMs?: number;
     fetch?: FetchLike;
@@ -224,6 +224,12 @@ export interface UpdateVideoOutroImageInput {
     sessionID?: string;
     request_id?: string;
     requestId?: string;
+    source_request_id?: string;
+    sourceRequestId?: string;
+    external_request_id?: string;
+    externalRequestId?: string;
+    external_session_id?: string;
+    externalSessionId?: string;
     outro_image_url?: string;
     outroImageUrl?: string;
     new_outro_image_url?: string;
@@ -265,6 +271,12 @@ export interface AddVideoOutroImageInput {
     sessionID?: string;
     request_id?: string;
     requestId?: string;
+    source_request_id?: string;
+    sourceRequestId?: string;
+    external_request_id?: string;
+    externalRequestId?: string;
+    external_session_id?: string;
+    externalSessionId?: string;
     outro_image_url?: string;
     outroImageUrl?: string;
     new_outro_image_url?: string;
@@ -1294,6 +1306,89 @@ export interface ExternalRequestsListResponse {
     externalUser?: ExternalUserSummary | null;
     [key: string]: unknown;
 }
+export interface V2RequestOptions extends SamsarRequestOptions {
+    externalUser?: ExternalUserIdentity | null;
+    webhookUrl?: string;
+}
+export interface V2SessionResponse {
+    account_type?: 'internal' | 'external' | string;
+    auth_type?: string;
+    user?: {
+        id?: string;
+        email?: string | null;
+        displayName?: string | null;
+        username?: string | null;
+        pfpUrl?: string | null;
+        preferredLanguage?: string | null;
+        [key: string]: unknown;
+    };
+    external_api_key?: string | null;
+    external_user?: ExternalUserSummary | null;
+    externalUser?: ExternalUserSummary | null;
+    remainingCredits?: number | null;
+    [key: string]: unknown;
+}
+export interface V2RequestsListResponse {
+    requests: Array<ExternalRequestSummary | Record<string, unknown>>;
+    external_user?: ExternalUserSummary | null;
+    externalUser?: ExternalUserSummary | null;
+    [key: string]: unknown;
+}
+export interface V2UserRechargeCreditsRequest {
+    amount: number;
+    email: string;
+    redirect_url?: string;
+    redirectUrl?: string;
+    [key: string]: unknown;
+}
+export interface V2UserRechargeCreditsResponse {
+    url: string;
+    checkoutSessionId?: string | null;
+    paymentStatusEndpoint?: string;
+    amount: number;
+    amountCents: number;
+    credits: number;
+    currency: string;
+    redirectUrl?: string;
+    [key: string]: unknown;
+}
+export interface V2UserTokenRefreshRequest {
+    refreshToken?: string;
+    refresh_token?: string;
+}
+export interface V2UserTokenResponse {
+    tokenType?: 'Bearer' | string;
+    authToken: string;
+    refreshToken: string;
+    expiryDate: string;
+    expiresInSeconds?: number;
+    refreshTokenExpiresAt?: string;
+    [key: string]: unknown;
+}
+export interface UsageLogItem {
+    id?: string;
+    source?: string;
+    credits?: number;
+    balanceAfter?: number | null;
+    metadata?: Record<string, unknown>;
+    direction?: string;
+    createdAt?: string;
+    updatedAt?: string;
+    [key: string]: unknown;
+}
+export interface UsageLogsResponse {
+    items: UsageLogItem[];
+    pagination?: {
+        page?: number;
+        pageSize?: number;
+        totalItems?: number;
+        totalPages?: number;
+        hasNextPage?: boolean;
+        hasPreviousPage?: boolean;
+        [key: string]: unknown;
+    };
+    [key: string]: unknown;
+}
 export interface ExternalArchiveResponse {
     request?: ExternalRequestSummary | null;
     external_user?: ExternalUserSummary | null;
@@ -1476,13 +1571,49 @@ export declare class SamsarRequestError extends Error {
     constructor(message: string, init: SamsarErrorInit);
 }
 export declare class SamsarClient {
-    private readonly apiKey;
+    private readonly apiKey?;
     private readonly baseUrl;
     private readonly timeoutMs;
     private readonly fetchFn;
     private readonly defaultHeaders;
     private readonly externalUserApiKey?;
     constructor(options: SamsarClientOptions);
+    /**
+     * Low-level POST adapter for the upcoming /v2 omni routes.
+     * Pass options.externalUser to include an external_user payload; omit it for internal-account calls
+     * or when authenticating directly with an external-user auth token/API key.
+     */
+    postV2<T = Record<string, unknown>>(path: string, payload?: Record<string, unknown>, options?: V2RequestOptions): Promise<SamsarResult<T>>;
+    /**
+     * Low-level GET adapter for the upcoming /v2 omni routes.
+     */
+    getV2<T = Record<string, unknown>>(path: string, options?: V2RequestOptions): Promise<SamsarResult<T>>;
+    createV2Session(options?: V2RequestOptions): Promise<SamsarResult<V2SessionResponse>>;
+    getV2Credits(options?: V2RequestOptions): Promise<SamsarResult<CreditsBalanceResponse | ExternalCreditsBalanceResponse>>;
+    getV2UserCredits(options?: V2RequestOptions): Promise<SamsarResult<CreditsBalanceResponse>>;
+    getV2UserUsageLogs(options?: V2RequestOptions & {
+        page?: number;
+        pageSize?: number;
+        limit?: number;
+    }): Promise<SamsarResult<UsageLogsResponse>>;
+    listV2Requests(options?: V2RequestOptions): Promise<SamsarResult<V2RequestsListResponse>>;
+    createV2UserRechargeCredits(payload: V2UserRechargeCreditsRequest, options?: V2RequestOptions): Promise<SamsarResult<V2UserRechargeCreditsResponse>>;
+    refreshV2UserToken(payload: string | V2UserTokenRefreshRequest, options?: V2RequestOptions): Promise<SamsarResult<V2UserTokenResponse>>;
+    refreshV2UserAuthToken(payload: string | V2UserTokenRefreshRequest, options?: V2RequestOptions): Promise<SamsarResult<V2UserTokenResponse>>;
+    getV2UserPaymentStatus(payload: PaymentStatusRequest, options?: V2RequestOptions): Promise<SamsarResult<PaymentStatusResponse>>;
+    createV2LoginToken(options?: V2RequestOptions & {
+        redirect?: string;
+    }): Promise<SamsarResult<CreateLoginTokenResponse | ExternalCreateLoginTokenResponse>>;
+    createV2VideoFromText(input: CreateVideoFromTextInput, options?: V2RequestOptions): Promise<SamsarResult<CreateVideoResponse | ExternalRequestResponse>>;
+    createV2VideoFromImageList(input: CreateVideoFromImageListInput, options?: V2RequestOptions): Promise<SamsarResult<CreateVideoFromImageListResponse | ExternalRequestResponse>>;
+    uploadV2ImageData(imageData: string[], options?: V2RequestOptions): Promise<SamsarResult<{
+        image_urls: string[];
+    }>>;
+    updateV2VideoOutroImage(input: UpdateVideoOutroImageInput, options?: V2RequestOptions): Promise<SamsarResult<UpdateVideoOutroImageResponse | ExternalRequestResponse>>;
+    addV2VideoOutroImage(input: AddVideoOutroImageInput, options?: V2RequestOptions): Promise<SamsarResult<AddVideoOutroImageResponse | ExternalRequestResponse>>;
+    getV2Status(requestId: string, options?: V2RequestOptions & {
+        queryParams?: QueryParams;
+    }): Promise<SamsarResult<GlobalStatusResponse | ExternalStatusResponse>>;
     /**
      * Create a new video generation job from text.
      */
@@ -1584,6 +1715,13 @@ export declare class SamsarClient {
     updateVideoOutroImage(input: UpdateVideoOutroImageInput, options?: {
         webhookUrl?: string;
     } & SamsarRequestOptions): Promise<SamsarResult<UpdateVideoOutroImageResponse>>;
+    /**
+     * Update the outro image for an external-user video request by resolving the external request id
+     * through /external_users/update_outro_image.
+     */
+    updateExternalVideoOutroImage(externalUser: ExternalUserIdentity, input: UpdateVideoOutroImageInput, options?: {
+        webhookUrl?: string;
+    } & SamsarRequestOptions): Promise<SamsarResult<ExternalRequestResponse>>;
     /**
      * Add or replace the outro image for an existing video session by cloning it into a new session and
      * re-running frame/video generation.
@@ -1591,6 +1729,12 @@ export declare class SamsarClient {
     addVideoOutroImage(input: AddVideoOutroImageInput, options?: {
         webhookUrl?: string;
     } & SamsarRequestOptions): Promise<SamsarResult<AddVideoOutroImageResponse>>;
+    /**
+     * Add or replace an outro image for an external-user video request by resolving the external request id.
+     */
+    addExternalVideoOutroImage(externalUser: ExternalUserIdentity, input: AddVideoOutroImageInput, options?: {
+        webhookUrl?: string;
+    } & SamsarRequestOptions): Promise<SamsarResult<ExternalRequestResponse>>;
     /**
      * Fetch the latest available render URL for a given video session id.
      * Maps to GET /video/fetch_latest_version?session_id={sessionId}.
@@ -1826,5 +1970,7 @@ export declare class SamsarClient {
     private buildHeaders;
     private buildUrl;
     private buildRootUrl;
+    private withV2ExternalUser;
+    private buildV2Url;
 }
 export default SamsarClient;

package/dist/index.js

@@ -126,6 +126,96 @@ function normalizeCreateVideoFromImageListInput(input) {
     }
     return normalized;
 }
+function normalizeUpdateVideoOutroImageInput(input, context = 'updateVideoOutroImage') {
+    const raw = input;
+    const videoSessionId = raw.videoSessionId ??
+        raw.video_session_id ??
+        raw.videoSessionID ??
+        raw.session_id ??
+        raw.sessionId ??
+        raw.sessionID ??
+        raw.request_id ??
+        raw.requestId ??
+        raw.source_request_id ??
+        raw.sourceRequestId ??
+        raw.external_request_id ??
+        raw.externalRequestId ??
+        raw.external_session_id ??
+        raw.externalSessionId;
+    const outroImageUrl = raw.outro_image_url ??
+        raw.outroImageUrl ??
+        raw.new_outro_image_url ??
+        raw.newOutroImageUrl;
+    const rawGenerateOutroImage = raw.generate_outro_image ??
+        raw.generateOutroImage;
+    const rawAddOutroAnimation = raw.add_outro_animation ??
+        raw.addOutroAnimation;
+    const rawAddOutroFocusArea = raw.add_outro_focus_area ??
+        raw.addOutroFocusArea;
+    const rawOutroFocusArea = raw.outro_focust_area ??
+        raw.outro_focus_area ??
+        raw.outroFocustArea ??
+        raw.outroFocusArea;
+    const ctaUrl = raw.cta_url ??
+        raw.ctaUrl;
+    const ctaTextTop = raw.cta_text_top ??
+        raw.ctaTextTop;
+    const ctaTextBottom = raw.cta_text_bottom ??
+        raw.ctaTextBottom;
+    const ctaLogo = raw.cta_logo ??
+        raw.ctaLogo;
+    const generateOutroImage = rawGenerateOutroImage === true ||
+        (rawGenerateOutroImage === undefined && !outroImageUrl && Boolean(ctaUrl));
+    if (!videoSessionId) {
+        throw new Error(`videoSessionId is required for ${context}`);
+    }
+    if (rawGenerateOutroImage !== undefined && typeof rawGenerateOutroImage !== 'boolean') {
+        throw new Error(`generate_outro_image must be a boolean for ${context}`);
+    }
+    if (rawAddOutroAnimation !== undefined && typeof rawAddOutroAnimation !== 'boolean') {
+        throw new Error(`add_outro_animation must be a boolean for ${context}`);
+    }
+    if (rawAddOutroFocusArea !== undefined && typeof rawAddOutroFocusArea !== 'boolean') {
+        throw new Error(`add_outro_focus_area must be a boolean for ${context}`);
+    }
+    if (generateOutroImage && outroImageUrl) {
+        throw new Error(`Use either generate_outro_image with cta_url or outro_image_url for ${context}`);
+    }
+    if (!generateOutroImage && !outroImageUrl) {
+        throw new Error(`outro_image_url is required for ${context} unless generate_outro_image is true`);
+    }
+    if (generateOutroImage) {
+        if (!ctaUrl || !String(ctaUrl).trim()) {
+            throw new Error(`cta_url is required when generate_outro_image is true for ${context}`);
+        }
+    }
+    else if (rawAddOutroFocusArea === true && rawAddOutroAnimation !== true) {
+        throw new Error(`add_outro_focus_area requires add_outro_animation to be true for ${context}`);
+    }
+    if (!generateOutroImage && rawAddOutroFocusArea === true) {
+        if (!rawOutroFocusArea || typeof rawOutroFocusArea !== 'object' || Array.isArray(rawOutroFocusArea)) {
+            throw new Error(`outro_focust_area must be an object with x, y, width, height for ${context}`);
+        }
+        const { x, y, width, height } = rawOutroFocusArea;
+        const isInvalid = [x, y, width, height].some((value) => typeof value !== 'number' || !Number.isFinite(value));
+        if (isInvalid) {
+            throw new Error(`outro_focust_area x, y, width, height must be valid numbers for ${context}`);
+        }
+    }
+    return {
+        ...input,
+        videoSessionId: String(videoSessionId),
+        ...(outroImageUrl ? { outro_image_url: String(outroImageUrl) } : {}),
+        generate_outro_image: generateOutroImage,
+        ...(generateOutroImage ? { cta_url: String(ctaUrl).trim() } : {}),
+        ...(ctaTextTop ? { cta_text_top: String(ctaTextTop) } : {}),
+        ...(ctaTextBottom ? { cta_text_bottom: String(ctaTextBottom) } : {}),
+        ...(ctaLogo ? { cta_logo: String(ctaLogo) } : {}),
+        ...(rawAddOutroAnimation !== undefined ? { add_outro_animation: rawAddOutroAnimation === true } : {}),
+        ...(rawAddOutroFocusArea !== undefined ? { add_outro_focus_area: rawAddOutroFocusArea === true } : {}),
+        ...(rawOutroFocusArea !== undefined ? { outro_focust_area: rawOutroFocusArea } : {}),
+    };
+}
 function normalizeSessionPublicationInput(input, context) {
     if (typeof input !== 'string' && (!input || typeof input !== 'object' || Array.isArray(input))) {
         throw new Error(`input must be a session id or object for ${context}`);
@@ -180,10 +270,7 @@ function normalizeSessionPublicationInput(input, context) {
 }
 export class SamsarClient {
     constructor(options) {
-        if (!options?.apiKey) {
-            throw new Error('apiKey is required to initialize SamsarClient');
-        }
-        this.apiKey = options.apiKey;
+        this.apiKey = options?.apiKey?.trim() || undefined;
         this.baseUrl = trimTrailingSlash(options.baseUrl ?? DEFAULT_BASE_URL);
         this.timeoutMs = options.timeoutMs ?? 30000;
         this.fetchFn = options.fetch ?? globalThis.fetch;
@@ -193,6 +280,155 @@ export class SamsarClient {
             throw new Error('A fetch implementation is required. Provide one via the "fetch" option when running outside environments with global fetch.');
         }
     }
+    /**
+     * Low-level POST adapter for the upcoming /v2 omni routes.
+     * Pass options.externalUser to include an external_user payload; omit it for internal-account calls
+     * or when authenticating directly with an external-user auth token/API key.
+     */
+    async postV2(path, payload = {}, options) {
+        return this.post(this.buildV2Url(path), this.withV2ExternalUser(payload, options), options);
+    }
+    /**
+     * Low-level GET adapter for the upcoming /v2 omni routes.
+     */
+    async getV2(path, options) {
+        const query = {
+            ...(options?.externalUser ? buildExternalUserQuery(options.externalUser) : {}),
+            ...(options?.query ?? {}),
+        };
+        return this.get(this.buildV2Url(path), { ...(options ?? {}), query });
+    }
+    async createV2Session(options) {
+        return this.postV2('session', {}, options);
+    }
+    async getV2Credits(options) {
+        return this.getV2('credits', options);
+    }
+    async getV2UserCredits(options) {
+        return this.getV2('user/credits', options);
+    }
+    async getV2UserUsageLogs(options) {
+        const query = {
+            ...(options?.query ?? {}),
+        };
+        if (options?.page !== undefined) {
+            query.page = options.page;
+        }
+        if (options?.pageSize !== undefined) {
+            query.pageSize = options.pageSize;
+        }
+        if (options?.limit !== undefined) {
+            query.limit = options.limit;
+        }
+        return this.getV2('user/usage/logs', {
+            ...(options ?? {}),
+            query,
+        });
+    }
+    async listV2Requests(options) {
+        return this.getV2('requests', options);
+    }
+    async createV2UserRechargeCredits(payload, options) {
+        const amount = Number(payload?.amount);
+        if (!Number.isFinite(amount) || amount <= 0) {
+            throw new Error('amount must be a positive dollar amount');
+        }
+        if (!payload?.email || typeof payload.email !== 'string') {
+            throw new Error('email is required');
+        }
+        const redirectUrl = payload.redirect_url ?? payload.redirectUrl;
+        if (!redirectUrl || typeof redirectUrl !== 'string') {
+            throw new Error('redirect_url is required');
+        }
+        return this.postV2('user/recharge_credits', {
+            ...payload,
+            amount,
+            email: payload.email.trim(),
+            redirect_url: redirectUrl.trim(),
+        }, options);
+    }
+    async refreshV2UserToken(payload, options) {
+        const refreshToken = typeof payload === 'string'
+            ? payload
+            : (payload?.refreshToken ?? payload?.refresh_token);
+        if (!refreshToken || typeof refreshToken !== 'string') {
+            throw new Error('refreshToken is required');
+        }
+        return this.postV2('user/refresh_token', { refreshToken: refreshToken.trim() }, options);
+    }
+    async refreshV2UserAuthToken(payload, options) {
+        return this.refreshV2UserToken(payload, options);
+    }
+    async getV2UserPaymentStatus(payload, options) {
+        const query = {
+            ...(options?.query ?? {}),
+        };
+        if (payload?.checkoutSessionId) {
+            query.checkoutSessionId = payload.checkoutSessionId;
+        }
+        if (payload?.paymentIntentId) {
+            query.paymentIntentId = payload.paymentIntentId;
+        }
+        if (payload?.setupIntentId) {
+            query.setupIntentId = payload.setupIntentId;
+        }
+        return this.getV2('user/payment_status', {
+            ...(options ?? {}),
+            query,
+        });
+    }
+    async createV2LoginToken(options) {
+        const body = options?.redirect ? { redirect: options.redirect } : {};
+        return this.postV2('create_login_token', body, options);
+    }
+    async createV2VideoFromText(input, options) {
+        const normalizedInput = normalizeCreateVideoFromTextInput(input);
+        return this.postV2('text_to_video', {
+            input: normalizedInput,
+            webhookUrl: options?.webhookUrl,
+        }, options);
+    }
+    async createV2VideoFromImageList(input, options) {
+        const normalizedInput = normalizeCreateVideoFromImageListInput(input);
+        return this.postV2('image_list_to_video', {
+            input: normalizedInput,
+            webhookUrl: options?.webhookUrl,
+        }, options);
+    }
+    async uploadV2ImageData(imageData, options) {
+        if (!Array.isArray(imageData) || imageData.length === 0) {
+            throw new Error('imageData must be a non-empty array of data URLs');
+        }
+        return this.postV2('upload_image_data', {
+            input: {
+                image_data: imageData,
+            },
+        }, options);
+    }
+    async updateV2VideoOutroImage(input, options) {
+        const normalizedInput = normalizeUpdateVideoOutroImageInput(input, 'updateV2VideoOutroImage');
+        return this.postV2('update_outro_image', {
+            input: normalizedInput,
+            webhookUrl: options?.webhookUrl,
+        }, options);
+    }
+    async addV2VideoOutroImage(input, options) {
+        return this.postV2('add_outro_image', {
+            input,
+            webhookUrl: options?.webhookUrl,
+        }, options);
+    }
+    async getV2Status(requestId, options) {
+        const queryParams = {
+            ...(options?.externalUser ? buildExternalUserQuery(options.externalUser) : {}),
+            ...(options?.queryParams ?? {}),
+        };
+        return this.getStatus(requestId, {
+            ...options,
+            path: this.buildV2Url('status'),
+            queryParams,
+        });
+    }
     /**
      * Create a new video generation job from text.
      */
@@ -563,6 +799,50 @@ export class SamsarClient {
      * only the final video render step.
      */
     async updateVideoOutroImage(input, options) {
+        const normalizedInput = normalizeUpdateVideoOutroImageInput(input, 'updateVideoOutroImage');
+        const body = {
+            input: normalizedInput,
+            webhookUrl: options?.webhookUrl,
+        };
+        const response = await this.post('video/update_outro_image', body, options);
+        const data = response.data;
+        if (data && typeof data === 'object') {
+            const sessionId = typeof data.sessionID === 'string'
+                ? data.sessionID
+                : typeof data.session_id === 'string'
+                    ? data.session_id
+                    : typeof data.request_id === 'string'
+                        ? data.request_id
+                        : undefined;
+            const normalizedSessionId = sessionId ? String(sessionId) : undefined;
+            const normalizedData = {
+                ...data,
+                sessionID: data.sessionID ?? normalizedSessionId ?? '',
+                session_id: data.session_id ?? normalizedSessionId,
+                request_id: data.request_id ?? normalizedSessionId,
+            };
+            return { ...response, data: normalizedData };
+        }
+        return response;
+    }
+    /**
+     * Update the outro image for an external-user video request by resolving the external request id
+     * through /external_users/update_outro_image.
+     */
+    async updateExternalVideoOutroImage(externalUser, input, options) {
+        const normalizedInput = normalizeUpdateVideoOutroImageInput(input, 'updateExternalVideoOutroImage');
+        const body = {
+            external_user: normalizeExternalUserIdentity(externalUser),
+            input: normalizedInput,
+            webhookUrl: options?.webhookUrl,
+        };
+        return this.post('external_users/update_outro_image', body, options);
+    }
+    /**
+     * Add or replace the outro image for an existing video session by cloning it into a new session and
+     * re-running frame/video generation.
+     */
+    async addVideoOutroImage(input, options) {
         const raw = input;
         const videoSessionId = raw.videoSessionId ??
             raw.video_session_id ??
@@ -576,8 +856,6 @@ export class SamsarClient {
             raw.outroImageUrl ??
             raw.new_outro_image_url ??
             raw.newOutroImageUrl;
-        const rawGenerateOutroImage = raw.generate_outro_image ??
-            raw.generateOutroImage;
         const rawAddOutroAnimation = raw.add_outro_animation ??
             raw.addOutroAnimation;
         const rawAddOutroFocusArea = raw.add_outro_focus_area ??
@@ -586,69 +864,43 @@ export class SamsarClient {
             raw.outro_focus_area ??
             raw.outroFocustArea ??
             raw.outroFocusArea;
-        const ctaUrl = raw.cta_url ??
-            raw.ctaUrl;
-        const ctaTextTop = raw.cta_text_top ??
-            raw.ctaTextTop;
-        const ctaTextBottom = raw.cta_text_bottom ??
-            raw.ctaTextBottom;
-        const ctaLogo = raw.cta_logo ??
-            raw.ctaLogo;
-        const generateOutroImage = rawGenerateOutroImage === true ||
-            (rawGenerateOutroImage === undefined && !outroImageUrl && Boolean(ctaUrl));
         if (!videoSessionId) {
-            throw new Error('videoSessionId is required for updateVideoOutroImage');
+            throw new Error('videoSessionId is required for addVideoOutroImage');
         }
-        if (rawGenerateOutroImage !== undefined && typeof rawGenerateOutroImage !== 'boolean') {
-            throw new Error('generate_outro_image must be a boolean for updateVideoOutroImage');
+        if (!outroImageUrl) {
+            throw new Error('outro_image_url is required for addVideoOutroImage');
         }
         if (rawAddOutroAnimation !== undefined && typeof rawAddOutroAnimation !== 'boolean') {
-            throw new Error('add_outro_animation must be a boolean for updateVideoOutroImage');
+            throw new Error('add_outro_animation must be a boolean for addVideoOutroImage');
         }
         if (rawAddOutroFocusArea !== undefined && typeof rawAddOutroFocusArea !== 'boolean') {
-            throw new Error('add_outro_focus_area must be a boolean for updateVideoOutroImage');
-        }
-        if (generateOutroImage && outroImageUrl) {
-            throw new Error('Use either generate_outro_image with cta_url or outro_image_url for updateVideoOutroImage');
-        }
-        if (!generateOutroImage && !outroImageUrl) {
-            throw new Error('outro_image_url is required for updateVideoOutroImage unless generate_outro_image is true');
-        }
-        if (generateOutroImage) {
-            if (!ctaUrl || !String(ctaUrl).trim()) {
-                throw new Error('cta_url is required when generate_outro_image is true for updateVideoOutroImage');
-            }
+            throw new Error('add_outro_focus_area must be a boolean for addVideoOutroImage');
         }
-        else if (rawAddOutroFocusArea === true && rawAddOutroAnimation !== true) {
-            throw new Error('add_outro_focus_area requires add_outro_animation to be true for updateVideoOutroImage');
+        if (rawAddOutroFocusArea === true && rawAddOutroAnimation !== true) {
+            throw new Error('add_outro_focus_area requires add_outro_animation to be true for addVideoOutroImage');
         }
-        if (!generateOutroImage && rawAddOutroFocusArea === true) {
+        if (rawAddOutroFocusArea === true) {
             if (!rawOutroFocusArea || typeof rawOutroFocusArea !== 'object' || Array.isArray(rawOutroFocusArea)) {
-                throw new Error('outro_focust_area must be an object with x, y, width, height for updateVideoOutroImage');
+                throw new Error('outro_focust_area must be an object with x, y, width, height for addVideoOutroImage');
             }
             const { x, y, width, height } = rawOutroFocusArea;
             const isInvalid = [x, y, width, height].some((value) => typeof value !== 'number' || !Number.isFinite(value));
             if (isInvalid) {
-                throw new Error('outro_focust_area x, y, width, height must be valid numbers for updateVideoOutroImage');
+                throw new Error('outro_focust_area x, y, width, height must be valid numbers for addVideoOutroImage');
             }
         }
         const body = {
             input: {
                 ...input,
                 videoSessionId: String(videoSessionId),
-                ...(outroImageUrl ? { outro_image_url: String(outroImageUrl) } : {}),
-                generate_outro_image: generateOutroImage,
-                ...(generateOutroImage ? { cta_url: String(ctaUrl).trim() } : {}),
-                ...(ctaTextTop ? { cta_text_top: String(ctaTextTop) } : {}),
-                ...(ctaTextBottom ? { cta_text_bottom: String(ctaTextBottom) } : {}),
-                ...(ctaLogo ? { cta_logo: String(ctaLogo) } : {}),
+                outro_image_url: String(outroImageUrl),
                 ...(rawAddOutroAnimation !== undefined ? { add_outro_animation: rawAddOutroAnimation === true } : {}),
                 ...(rawAddOutroFocusArea !== undefined ? { add_outro_focus_area: rawAddOutroFocusArea === true } : {}),
                 ...(rawOutroFocusArea !== undefined ? { outro_focust_area: rawOutroFocusArea } : {}),
             },
             webhookUrl: options?.webhookUrl,
         };
-        const response = await this.post('video/update_outro_image', body, options);
+        const response = await this.post('video/add_outro_image', body, options);
         const data = response.data;
         if (data && typeof data === 'object') {
             const sessionId = typeof data.sessionID === 'string'
@@ -670,10 +922,9 @@ export class SamsarClient {
         return response;
     }
     /**
-     * Add or replace the outro image for an existing video session by cloning it into a new session and
-     * re-running frame/video generation.
+     * Add or replace an outro image for an external-user video request by resolving the external request id.
      */
-    async addVideoOutroImage(input, options) {
+    async addExternalVideoOutroImage(externalUser, input, options) {
         const raw = input;
         const videoSessionId = raw.videoSessionId ??
             raw.video_session_id ??
@@ -682,7 +933,13 @@ export class SamsarClient {
             raw.sessionId ??
             raw.sessionID ??
             raw.request_id ??
-            raw.requestId;
+            raw.requestId ??
+            raw.source_request_id ??
+            raw.sourceRequestId ??
+            raw.external_request_id ??
+            raw.externalRequestId ??
+            raw.external_session_id ??
+            raw.externalSessionId;
         const outroImageUrl = raw.outro_image_url ??
             raw.outroImageUrl ??
             raw.new_outro_image_url ??
@@ -696,31 +953,32 @@ export class SamsarClient {
             raw.outroFocustArea ??
             raw.outroFocusArea;
         if (!videoSessionId) {
-            throw new Error('videoSessionId is required for addVideoOutroImage');
+            throw new Error('videoSessionId is required for addExternalVideoOutroImage');
         }
         if (!outroImageUrl) {
-            throw new Error('outro_image_url is required for addVideoOutroImage');
+            throw new Error('outro_image_url is required for addExternalVideoOutroImage');
         }
         if (rawAddOutroAnimation !== undefined && typeof rawAddOutroAnimation !== 'boolean') {
-            throw new Error('add_outro_animation must be a boolean for addVideoOutroImage');
+            throw new Error('add_outro_animation must be a boolean for addExternalVideoOutroImage');
         }
         if (rawAddOutroFocusArea !== undefined && typeof rawAddOutroFocusArea !== 'boolean') {
-            throw new Error('add_outro_focus_area must be a boolean for addVideoOutroImage');
+            throw new Error('add_outro_focus_area must be a boolean for addExternalVideoOutroImage');
         }
         if (rawAddOutroFocusArea === true && rawAddOutroAnimation !== true) {
-            throw new Error('add_outro_focus_area requires add_outro_animation to be true for addVideoOutroImage');
+            throw new Error('add_outro_focus_area requires add_outro_animation to be true for addExternalVideoOutroImage');
         }
         if (rawAddOutroFocusArea === true) {
             if (!rawOutroFocusArea || typeof rawOutroFocusArea !== 'object' || Array.isArray(rawOutroFocusArea)) {
-                throw new Error('outro_focust_area must be an object with x, y, width, height for addVideoOutroImage');
+                throw new Error('outro_focust_area must be an object with x, y, width, height for addExternalVideoOutroImage');
             }
             const { x, y, width, height } = rawOutroFocusArea;
             const isInvalid = [x, y, width, height].some((value) => typeof value !== 'number' || !Number.isFinite(value));
             if (isInvalid) {
-                throw new Error('outro_focust_area x, y, width, height must be valid numbers for addVideoOutroImage');
+                throw new Error('outro_focust_area x, y, width, height must be valid numbers for addExternalVideoOutroImage');
             }
         }
         const body = {
+            external_user: normalizeExternalUserIdentity(externalUser),
             input: {
                 ...input,
                 videoSessionId: String(videoSessionId),
@@ -731,26 +989,7 @@ export class SamsarClient {
             },
             webhookUrl: options?.webhookUrl,
         };
-        const response = await this.post('video/add_outro_image', body, options);
-        const data = response.data;
-        if (data && typeof data === 'object') {
-            const sessionId = typeof data.sessionID === 'string'
-                ? data.sessionID
-                : typeof data.session_id === 'string'
-                    ? data.session_id
-                    : typeof data.request_id === 'string'
-                        ? data.request_id
-                        : undefined;
-            const normalizedSessionId = sessionId ? String(sessionId) : undefined;
-            const normalizedData = {
-                ...data,
-                sessionID: data.sessionID ?? normalizedSessionId ?? '',
-                session_id: data.session_id ?? normalizedSessionId,
-                request_id: data.request_id ?? normalizedSessionId,
-            };
-            return { ...response, data: normalizedData };
-        }
-        return response;
+        return this.post('external_users/add_outro_image', body, options);
     }
     /**
      * Fetch the latest available render URL for a given video session id.
@@ -1448,7 +1687,7 @@ export class SamsarClient {
     }
     buildHeaders(options) {
         const headers = {
-            Authorization: `Bearer ${this.apiKey}`,
+            Authorization: this.apiKey ? `Bearer ${this.apiKey}` : undefined,
             'Content-Type': options.body ? 'application/json' : undefined,
             'x-external-user-api-key': options.externalUserApiKey ?? this.externalUserApiKey,
             ...this.defaultHeaders,
@@ -1478,6 +1717,19 @@ export class SamsarClient {
         const rootUrl = baseUrl.endsWith('/v1') ? baseUrl.slice(0, -3) : baseUrl;
         return `${rootUrl}/${cleanedPath}`;
     }
+    withV2ExternalUser(body, options) {
+        if (!options?.externalUser) {
+            return body;
+        }
+        return {
+            ...body,
+            external_user: normalizeExternalUserIdentity(options.externalUser),
+        };
+    }
+    buildV2Url(path) {
+        const cleanedPath = path.replace(/^\/+/, '');
+        return this.buildRootUrl(`v2/${cleanedPath}`);
+    }
 }
 function trimTrailingSlash(url) {
     return url.replace(/\/+$/, '');

package/package.json

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