samsar-js 0.48.2 → 0.48.4

package/README.md

@@ -112,6 +112,17 @@ const embedding = await samsar.createEmbedding({
 // field_options controls which fields are embedded, used for structured filters, and returned in raw results.
 // Use dot-notated paths (e.g. owner.email) or inline wrappers like { value, searchable, filterable, retrievable }.
 
+// Create embeddings from one URL or a URL list
+const websiteEmbedding = await samsar.createEmbeddingFromUrl({
+  name: 'product-docs',
+  urls: [
+    'https://example.com/docs/getting-started',
+    'https://example.com/docs/pricing',
+  ],
+});
+
+// The generic createEmbedding wrapper also accepts `urls` on the same route if you prefer one entrypoint.
+
 // Search against an embedding template
 const search = await samsar.searchAgainstEmbedding({
   template_id: embedding.data.template_id,
@@ -224,6 +235,66 @@ const paymentStatus = await samsar.getPaymentStatus({
 console.log(paymentStatus.data.status);
 ```
 
+## External users
+
+Use the external-user surface when many platform users share one central Samsar account and API key.
+
+```ts
+import SamsarClient from 'samsar-js';
+
+const platform = new SamsarClient({
+  apiKey: process.env.SAMSAR_PLATFORM_API_KEY!,
+});
+
+const externalUser = {
+  provider: 'whop',
+  external_user_id: 'usr_123',
+  external_app_id: 'app_abc',
+  username: 'roy24x7',
+};
+
+// Bootstrap or refresh the external user
+const externalSession = await platform.createExternalUserSession(externalUser);
+console.log(externalSession.data.remainingCredits, externalSession.data.external_api_key);
+
+// Create a render attributed to that external user
+const externalRender = await platform.createExternalVideoFromText(externalUser, {
+  prompt: 'A sleek teaser for a futuristic running shoe',
+  image_model: 'GPTIMAGE1',
+  video_model: 'RUNWAYML',
+  duration: 10,
+  enable_subtitles: true,
+});
+
+// Fetch their external library
+const library = await platform.listExternalUserRequests(externalUser, { limit: 12 });
+console.log(library.data.requests.length);
+
+// Publish or archive a render
+await platform.publishExternalUserRequest(externalRender.data.request_id, {
+  title: 'Running shoe teaser',
+}, externalUser);
+await platform.archiveExternalUserRequest(externalRender.data.request_id, externalUser);
+
+// Create a short-lived login URL for the external Studio dashboard
+const login = await platform.createExternalUserLoginToken(externalUser, {
+  redirect: '/external/studio',
+});
+console.log(login.data.loginUrl);
+
+// Exchange the login token for a client auth token
+const verified = await platform.verifyClientSession({
+  loginToken: login.data.loginToken,
+});
+
+// The returned authToken can be used as the SDK apiKey for external-user routes
+const externalClient = new SamsarClient({
+  apiKey: verified.data.authToken!,
+});
+const externalLibrary = await externalClient.listExternalUserRequests();
+console.log(externalLibrary.data.requests.map((request) => request.request_id));
+```
+
 Video model support notes:
 - `createVideoFromText` image model keys include: `GPTIMAGE1`, `IMAGEN4`, `SEEDREAM`, `HUNYUAN`, `NANOBANANA2`.
 - `createVideoFromText` supports all express video models: `RUNWAYML`, `KLINGIMGTOVID3PRO`, `HAILUO`, `HAILUOPRO`, `SEEDANCEI2V`, `VEO3.1I2V`, `VEO3.1I2VFAST`, `SORA2`, `SORA2PRO`.
@@ -234,6 +305,7 @@ Each method returns `{ data, status, headers, creditsCharged, creditsRemaining,
 ## Billing notes
 
 - Embedding endpoints (`createEmbedding`, `updateEmbedding`, `searchAgainstEmbedding`, `similarToEmbedding`) are billed by input tokens at $1 per million tokens. `deleteEmbeddings` does not consume tokens.
+- URL-based embedding creation (`createEmbedding` with `urls`, or `createEmbeddingFromUrl`) adds Firecrawl crawl cost to the embedding token cost, then applies Samsar's 100 credits per USD mapping with a `2.5x` multiplier.
 - Token counts follow OpenAI tokenization for `text-embedding-3-large`. Credit deductions follow the existing 100 credits per USD rule.
 - Receipt template creation (`createReceiptTemplate`) and template JSON lookup (`getReceiptTemplateJson`) are free; receipt template query (`queryReceiptTemplate`) costs 50 credits per request.
 
@@ -244,6 +316,7 @@ Each method returns `{ data, status, headers, creditsCharged, creditsRemaining,
 - `timeoutMs` (optional): defaults to 30s.
 - `fetch` (optional): supply a fetch implementation when not available globally (e.g., Node <18).
 - `defaultHeaders` (optional): merged into every request.
+- `externalUserApiKey` (optional): default `x-external-user-api-key` header for external-user scoped requests.
 
 ## Build
 

package/dist/index.d.ts

@@ -7,10 +7,12 @@ export interface SamsarClientOptions {
     timeoutMs?: number;
     fetch?: FetchLike;
     defaultHeaders?: Record<string, string>;
+    externalUserApiKey?: string;
 }
 export interface SamsarRequestOptions {
     idempotencyKey?: string;
     headers?: Record<string, string>;
+    externalUserApiKey?: string;
     signal?: AbortSignal;
     query?: QueryParams;
 }
@@ -306,6 +308,7 @@ export interface EmbeddingFieldOptions {
     filterable?: boolean;
     retrievable?: boolean;
 }
+export type EmbeddingUrlInput = string | string[];
 export type EmbeddingFieldOptionsInput = Record<string, EmbeddingFieldOptions> | Array<EmbeddingFieldOptions & {
     key?: string;
     field?: string;
@@ -314,8 +317,25 @@ export type EmbeddingFieldOptionsInput = Record<string, EmbeddingFieldOptions> |
     column_name?: string;
     columnName?: string;
 }>;
+export interface EmbeddingUrlIssue {
+    url?: string | null;
+    message?: string;
+    code?: string | null;
+}
 export interface CreateEmbeddingRequest {
-    records: Array<Record<string, unknown>>;
+    records?: Array<Record<string, unknown>>;
+    urls?: EmbeddingUrlInput;
+    url?: string;
+    name?: string;
+    embedding_name?: string;
+    template_name?: string;
+    field_options?: EmbeddingFieldOptionsInput;
+    fieldOptions?: EmbeddingFieldOptionsInput;
+    [key: string]: unknown;
+}
+export interface CreateEmbeddingFromUrlRequest {
+    urls?: EmbeddingUrlInput;
+    url?: string;
     name?: string;
     embedding_name?: string;
     template_name?: string;
@@ -328,6 +348,11 @@ export interface CreateEmbeddingResponse {
     template_hash?: string;
     hash_link?: string;
     record_count?: number;
+    input_url_count?: number;
+    processed_url_count?: number;
+    firecrawl_credits_used?: number;
+    skipped_urls?: EmbeddingUrlIssue[];
+    crawl_errors?: EmbeddingUrlIssue[];
     structured_fields?: EmbeddingStructuredField[];
     unstructured_fields?: string[];
     [key: string]: unknown;
@@ -754,6 +779,157 @@ export interface GlobalStatusResponse {
     message?: string | null;
     [key: string]: unknown;
 }
+export interface ExternalUserIdentity {
+    provider: string;
+    external_user_id?: string;
+    externalUserId?: string;
+    external_app_id?: string;
+    externalAppId?: string;
+    external_company_id?: string;
+    externalCompanyId?: string;
+    external_account_id?: string;
+    externalAccountId?: string;
+    email?: string;
+    username?: string;
+    display_name?: string;
+    displayName?: string;
+    avatar_url?: string;
+    avatarUrl?: string;
+    metadata?: Record<string, unknown>;
+    [key: string]: unknown;
+}
+export interface ExternalUserSummary {
+    id?: string | null;
+    provider?: string;
+    external_user_id?: string;
+    external_app_id?: string | null;
+    external_company_id?: string | null;
+    email?: string | null;
+    username?: string | null;
+    display_name?: string | null;
+    avatar_url?: string | null;
+    generation_credits?: number;
+    has_external_api_key?: boolean;
+    external_api_key_created_at?: string | null;
+    external_api_key_last_used_at?: string | null;
+    total_requests?: number;
+    total_credits_used?: number;
+    total_credits_refunded?: number;
+    total_credits_purchased?: number;
+    last_request_at?: string | null;
+    last_purchase_at?: string | null;
+    last_activity_at?: string | null;
+    created_at?: string | null;
+    updated_at?: string | null;
+    [key: string]: unknown;
+}
+export interface ExternalRequestResponse {
+    request_id: string;
+    session_id?: string;
+    external_request_id?: string;
+    external_session_id?: string;
+    upstream_request_id?: string | null;
+    upstream_session_id?: string | null;
+    status_endpoint?: string;
+    external_user?: ExternalUserSummary | null;
+    creditsCharged?: number;
+    creditsRefunded?: number;
+    remainingCredits?: number | null;
+    [key: string]: unknown;
+}
+export interface ExternalCreditsBalanceResponse extends CreditsBalanceResponse {
+    externalUser?: ExternalUserSummary | null;
+    external_user?: ExternalUserSummary | null;
+}
+export interface ExternalUserSessionResponse extends ExternalCreditsBalanceResponse {
+    external_api_key?: string | null;
+    external_user?: ExternalUserSummary | null;
+    externalUser?: ExternalUserSummary | null;
+}
+export interface ExternalCreditsGrantResponse {
+    creditsGranted: number;
+    remainingCredits: number;
+    internalRemainingCredits?: number | null;
+    externalUser?: ExternalUserSummary | null;
+    external_user?: ExternalUserSummary | null;
+    [key: string]: unknown;
+}
+export interface ExternalCreditsRechargeResponse extends CreditsRechargeResponse {
+    external_payment_id?: string;
+    external_user?: ExternalUserSummary | null;
+    externalUser?: ExternalUserSummary | null;
+}
+export interface ExternalPaymentStatusRequest extends PaymentStatusRequest {
+    external_payment_id?: string;
+    externalPaymentId?: string;
+}
+export interface ExternalPaymentStatusResponse extends PaymentStatusResponse {
+    external_payment_id?: string;
+    external_user?: ExternalUserSummary | null;
+    externalUser?: ExternalUserSummary | null;
+    remainingCredits?: number | null;
+    lastTopUp?: CreditTopUpSummary | null;
+}
+export interface ExternalStatusResponse extends GlobalStatusResponse {
+    external_request_id?: string;
+    external_session_id?: string;
+    upstream_request_id?: string | null;
+    upstream_session_id?: string | null;
+    external_user?: ExternalUserSummary | null;
+    creditsRefunded?: number;
+    remainingCredits?: number | null;
+}
+export interface ExternalRequestSummary {
+    request_id?: string;
+    external_request_id?: string;
+    upstream_request_id?: string | null;
+    upstream_session_id?: string | null;
+    route_key?: string | null;
+    status?: string | null;
+    prompt?: string | null;
+    video_url?: string | null;
+    image_count?: number;
+    credits_charged?: number;
+    credits_refunded?: number;
+    remaining_credits?: number | null;
+    target_language?: string | null;
+    source_request_ids?: string[];
+    source_session_ids?: string[];
+    created_at?: string | null;
+    updated_at?: string | null;
+    is_published?: boolean;
+    published_title?: string | null;
+    published_description?: string | null;
+    published_tags?: string[];
+    published_at?: string | null;
+    published_video_url?: string | null;
+    published_publication_id?: string | null;
+    [key: string]: unknown;
+}
+export interface ExternalRequestsListResponse {
+    requests: ExternalRequestSummary[];
+    external_user?: ExternalUserSummary | null;
+    externalUser?: ExternalUserSummary | null;
+    [key: string]: unknown;
+}
+export interface ExternalArchiveResponse {
+    request?: ExternalRequestSummary | null;
+    external_user?: ExternalUserSummary | null;
+    externalUser?: ExternalUserSummary | null;
+    [key: string]: unknown;
+}
+export interface ExternalPublishInput {
+    title?: string;
+    description?: string;
+    tags?: string[] | string;
+    aspectRatio?: string;
+    sessionLanguage?: string;
+    languageString?: string;
+    [key: string]: unknown;
+}
+export interface ExternalPublishResponse extends ExternalArchiveResponse {
+    publication?: Record<string, unknown> | null;
+}
 export interface CreditTopUpSummary {
     id?: string;
     amountPaidCents?: number;
@@ -783,6 +959,39 @@ export interface CreateLoginTokenResponse {
     expiresAt?: string;
     [key: string]: unknown;
 }
+export interface ExternalCreateLoginTokenResponse extends CreateLoginTokenResponse {
+    loginUrl?: string;
+    external_user?: ExternalUserSummary | null;
+    externalUser?: ExternalUserSummary | null;
+}
+export interface VerifyClientSessionInput {
+    loginToken?: string;
+    authToken?: string;
+}
+export interface VerifiedClientSessionResponse {
+    authToken?: string;
+    isExternalUser?: boolean;
+    _id?: string | null;
+    email?: string | null;
+    username?: string | null;
+    displayName?: string | null;
+    avatarUrl?: string | null;
+    provider?: string | null;
+    externalUserId?: string | null;
+    externalAppId?: string | null;
+    externalCompanyId?: string | null;
+    generationCredits?: number;
+    totalRequests?: number;
+    totalCreditsUsed?: number;
+    totalCreditsRefunded?: number;
+    totalCreditsPurchased?: number;
+    lastRequestAt?: string | null;
+    lastPurchaseAt?: string | null;
+    lastActivityAt?: string | null;
+    createdAt?: string | null;
+    updatedAt?: string | null;
+    [key: string]: unknown;
+}
 export interface CreditsRechargeResponse {
     url: string;
     checkoutSessionId?: string | null;
@@ -882,6 +1091,7 @@ export declare class SamsarClient {
     private readonly timeoutMs;
     private readonly fetchFn;
     private readonly defaultHeaders;
+    private readonly externalUserApiKey?;
     constructor(options: SamsarClientOptions);
     /**
      * Create a new video generation job from text.
@@ -895,6 +1105,34 @@ export declare class SamsarClient {
     createVideoFromImageList(input: CreateVideoFromImageListInput, options?: {
         webhookUrl?: string;
     } & SamsarRequestOptions): Promise<SamsarResult<CreateVideoFromImageListResponse>>;
+    /**
+     * Create a text-to-video request attributed to an external user while billing against the shared API key.
+     */
+    createExternalVideoFromText(externalUser: ExternalUserIdentity, input: CreateVideoFromTextInput, options?: {
+        webhookUrl?: string;
+    } & SamsarRequestOptions): Promise<SamsarResult<ExternalRequestResponse>>;
+    /**
+     * Upload image data URLs for an external user before calling createExternalVideoFromImageList.
+     */
+    uploadExternalImageData(externalUser: ExternalUserIdentity, imageData: string[], options?: SamsarRequestOptions): Promise<SamsarResult<{
+        image_urls: string[];
+    }>>;
+    /**
+     * Create an image-list-to-video request attributed to an external user while billing against the shared API key.
+     */
+    createExternalVideoFromImageList(externalUser: ExternalUserIdentity, input: CreateVideoFromImageListInput, options?: {
+        webhookUrl?: string;
+    } & SamsarRequestOptions): Promise<SamsarResult<ExternalRequestResponse>>;
+    /**
+     * Create or refresh an external-user session and receive that user’s dedicated external API key.
+     */
+    createExternalUserSession(externalUser: ExternalUserIdentity, options?: SamsarRequestOptions): Promise<SamsarResult<ExternalUserSessionResponse>>;
+    /**
+     * Create a short-lived external-user login token plus a ready-to-open client login URL.
+     */
+    createExternalUserLoginToken(externalUser?: ExternalUserIdentity | null, options?: ({
+        redirect?: string;
+    } & SamsarRequestOptions)): Promise<SamsarResult<ExternalCreateLoginTokenResponse>>;
     /**
      * Translate an existing video session into a new language.
      * Creates a new session_id and queues generation steps for lip sync + transcription + video render.
@@ -957,9 +1195,13 @@ export declare class SamsarClient {
      */
     enhanceMessage(payload: EnhanceMessageRequest, options?: SamsarRequestOptions): Promise<SamsarResult<EnhanceMessageResponse>>;
     /**
-     * Create a new embedding template and store embeddings for a JSON array.
+     * Create a new embedding template from either a JSON array (`records`) or a URL input (`urls`).
      */
     createEmbedding(payload: CreateEmbeddingRequest, options?: SamsarRequestOptions): Promise<SamsarResult<CreateEmbeddingResponse>>;
+    /**
+     * Create a new embedding template from one URL or a list of URLs.
+     */
+    createEmbeddingFromUrl(payload: CreateEmbeddingFromUrlRequest, options?: SamsarRequestOptions): Promise<SamsarResult<CreateEmbeddingResponse>>;
     /**
      * Update an existing embedding template with additional records.
      */
@@ -1037,6 +1279,28 @@ export declare class SamsarClient {
      * Fetch the remaining credits and last credit top-up for the API key.
      */
     getCreditsBalance(options?: SamsarRequestOptions): Promise<SamsarResult<CreditsBalanceResponse>>;
+    /**
+     * Fetch the shared credit balance plus attribution summary for a specific external user.
+     */
+    getExternalCreditsBalance(externalUser: ExternalUserIdentity, options?: SamsarRequestOptions): Promise<SamsarResult<ExternalCreditsBalanceResponse>>;
+    /**
+     * Manually grant credits to a specific external user while also crediting the shared platform account.
+     */
+    grantExternalUserCredits(externalUser: ExternalUserIdentity, credits: number, options?: SamsarRequestOptions): Promise<SamsarResult<ExternalCreditsGrantResponse>>;
+    /**
+     * Fetch recent external-user-attributed requests for library or dashboard views.
+     */
+    listExternalUserRequests(externalUser?: ExternalUserIdentity | null, options?: ({
+        limit?: number;
+    } & SamsarRequestOptions)): Promise<SamsarResult<ExternalRequestsListResponse>>;
+    /**
+     * Archive an external-user request so it no longer appears in the external library/feed.
+     */
+    archiveExternalUserRequest(requestId: string, externalUser?: ExternalUserIdentity | null, options?: SamsarRequestOptions): Promise<SamsarResult<ExternalArchiveResponse>>;
+    /**
+     * Publish a completed external-user request to the public library/feed.
+     */
+    publishExternalUserRequest(requestId: string, payload?: ExternalPublishInput, externalUser?: ExternalUserIdentity | null, options?: SamsarRequestOptions): Promise<SamsarResult<ExternalPublishResponse>>;
     /**
      * Create a short-lived login token that can be exchanged for an auth token in the client app.
      */
@@ -1046,6 +1310,10 @@ export declare class SamsarClient {
      * Business rule: 1 USD = 100 credits.
      */
     createCreditsRecharge(credits: number, options?: SamsarRequestOptions): Promise<SamsarResult<CreditsRechargeResponse>>;
+    /**
+     * Create a shared-balance Stripe recharge attributed to an external user.
+     */
+    createExternalCreditsRecharge(externalUser: ExternalUserIdentity, credits: number, options?: SamsarRequestOptions): Promise<SamsarResult<ExternalCreditsRechargeResponse>>;
     /**
      * Enable or update auto-recharge settings for the API key.
      * Returns a Stripe setup URL when a payment method is required.
@@ -1059,6 +1327,14 @@ export declare class SamsarClient {
      * Poll for checkout/payment/setup status using IDs returned by credit recharge or auto-recharge setup.
      */
     getPaymentStatus(payload: PaymentStatusRequest, options?: SamsarRequestOptions): Promise<SamsarResult<PaymentStatusResponse>>;
+    /**
+     * Poll shared-balance payment status for an external user credit purchase.
+     */
+    getExternalPaymentStatus(payload: ExternalPaymentStatusRequest, options?: SamsarRequestOptions): Promise<SamsarResult<ExternalPaymentStatusResponse>>;
+    /**
+     * Exchange a login token or verify an auth token against /users/verify_token.
+     */
+    verifyClientSession(payload: VerifyClientSessionInput, options?: SamsarRequestOptions): Promise<SamsarResult<VerifiedClientSessionResponse>>;
     /**
      * Retrieve the status of an asynchronous request by request_id.
      * Defaults to GET /status?request_id={requestId}, but the path can be overridden.
@@ -1068,6 +1344,12 @@ export declare class SamsarClient {
         path?: string;
         queryParams?: QueryParams;
     }): Promise<SamsarResult<GlobalStatusResponse>>;
+    /**
+     * Retrieve the status of an external-user-attributed asynchronous request by external request_id.
+     */
+    getExternalStatus(requestId: string, options?: SamsarRequestOptions & {
+        queryParams?: QueryParams;
+    }): Promise<SamsarResult<ExternalStatusResponse>>;
     /**
      * Retrieve the status of an image request (maps to GET /image/status).
      */
@@ -1079,5 +1361,6 @@ export declare class SamsarClient {
     private request;
     private buildHeaders;
     private buildUrl;
+    private buildRootUrl;
 }
 export default SamsarClient;

package/dist/index.js

@@ -25,6 +25,7 @@ export class SamsarClient {
         this.timeoutMs = options.timeoutMs ?? 30000;
         this.fetchFn = options.fetch ?? globalThis.fetch;
         this.defaultHeaders = options.defaultHeaders ?? {};
+        this.externalUserApiKey = options.externalUserApiKey?.trim() || undefined;
         if (typeof this.fetchFn !== 'function') {
             throw new Error('A fetch implementation is required. Provide one via the "fetch" option when running outside environments with global fetch.');
         }
@@ -68,6 +69,65 @@ export class SamsarClient {
         }
         return response;
     }
+    /**
+     * Create a text-to-video request attributed to an external user while billing against the shared API key.
+     */
+    async createExternalVideoFromText(externalUser, input, options) {
+        const body = {
+            external_user: normalizeExternalUserIdentity(externalUser),
+            input,
+            webhookUrl: options?.webhookUrl,
+        };
+        return this.post('external_users/text_to_video', body, options);
+    }
+    /**
+     * Upload image data URLs for an external user before calling createExternalVideoFromImageList.
+     */
+    async uploadExternalImageData(externalUser, imageData, options) {
+        if (!Array.isArray(imageData) || imageData.length === 0) {
+            throw new Error('imageData must be a non-empty array of data URLs');
+        }
+        const body = {
+            external_user: normalizeExternalUserIdentity(externalUser),
+            input: {
+                image_data: imageData,
+            },
+        };
+        return this.post('external_users/upload_image_data', body, options);
+    }
+    /**
+     * Create an image-list-to-video request attributed to an external user while billing against the shared API key.
+     */
+    async createExternalVideoFromImageList(externalUser, input, options) {
+        const body = {
+            external_user: normalizeExternalUserIdentity(externalUser),
+            input,
+            webhookUrl: options?.webhookUrl,
+        };
+        return this.post('external_users/image_list_to_video', body, options);
+    }
+    /**
+     * Create or refresh an external-user session and receive that user’s dedicated external API key.
+     */
+    async createExternalUserSession(externalUser, options) {
+        const body = {
+            external_user: normalizeExternalUserIdentity(externalUser),
+        };
+        return this.post('external_users/session', body, options);
+    }
+    /**
+     * Create a short-lived external-user login token plus a ready-to-open client login URL.
+     */
+    async createExternalUserLoginToken(externalUser, options) {
+        const body = {};
+        if (externalUser) {
+            body.external_user = normalizeExternalUserIdentity(externalUser);
+        }
+        if (options?.redirect) {
+            body.redirect = options.redirect;
+        }
+        return this.post('external_users/create_login_token', body, options);
+    }
     /**
      * Translate an existing video session into a new language.
      * Creates a new session_id and queues generation steps for lip sync + transcription + video render.
@@ -491,11 +551,17 @@ export class SamsarClient {
         return this.post('chat/enhance', payload, options);
     }
     /**
-     * Create a new embedding template and store embeddings for a JSON array.
+     * Create a new embedding template from either a JSON array (`records`) or a URL input (`urls`).
      */
     async createEmbedding(payload, options) {
         return this.post('chat/create_embedding', payload, options);
     }
+    /**
+     * Create a new embedding template from one URL or a list of URLs.
+     */
+    async createEmbeddingFromUrl(payload, options) {
+        return this.post('chat/create_embedding_from_url', payload, options);
+    }
     /**
      * Update an existing embedding template with additional records.
      */
@@ -684,6 +750,82 @@ export class SamsarClient {
     async getCreditsBalance(options) {
         return this.get('credits', options);
     }
+    /**
+     * Fetch the shared credit balance plus attribution summary for a specific external user.
+     */
+    async getExternalCreditsBalance(externalUser, options) {
+        return this.get('external_users/credits', {
+            ...(options ?? {}),
+            query: {
+                ...buildExternalUserQuery(externalUser),
+                ...(options?.query ?? {}),
+            },
+        });
+    }
+    /**
+     * Manually grant credits to a specific external user while also crediting the shared platform account.
+     */
+    async grantExternalUserCredits(externalUser, credits, options) {
+        if (!Number.isFinite(credits) || credits <= 0) {
+            throw new Error('credits must be a positive number');
+        }
+        const payload = {
+            external_user: normalizeExternalUserIdentity(externalUser),
+            input: {
+                credits: Math.round(credits),
+            },
+        };
+        return this.post('external_users/credits/grant', payload, options);
+    }
+    /**
+     * Fetch recent external-user-attributed requests for library or dashboard views.
+     */
+    async listExternalUserRequests(externalUser, options) {
+        const query = {
+            ...(options?.query ?? {}),
+        };
+        if (externalUser) {
+            Object.assign(query, buildExternalUserQuery(externalUser));
+        }
+        if (options?.limit !== undefined) {
+            query.limit = options.limit;
+        }
+        return this.get('external_users/requests', {
+            ...(options ?? {}),
+            query,
+        });
+    }
+    /**
+     * Archive an external-user request so it no longer appears in the external library/feed.
+     */
+    async archiveExternalUserRequest(requestId, externalUser, options) {
+        if (!requestId || typeof requestId !== 'string') {
+            throw new Error('requestId is required');
+        }
+        const payload = {
+            request_id: requestId,
+        };
+        if (externalUser) {
+            payload.external_user = normalizeExternalUserIdentity(externalUser);
+        }
+        return this.post('external_users/archive', payload, options);
+    }
+    /**
+     * Publish a completed external-user request to the public library/feed.
+     */
+    async publishExternalUserRequest(requestId, payload = {}, externalUser, options) {
+        if (!requestId || typeof requestId !== 'string') {
+            throw new Error('requestId is required');
+        }
+        const body = {
+            request_id: requestId,
+            ...payload,
+        };
+        if (externalUser) {
+            body.external_user = normalizeExternalUserIdentity(externalUser);
+        }
+        return this.post('external_users/publish', body, options);
+    }
     /**
      * Create a short-lived login token that can be exchanged for an auth token in the client app.
      */
@@ -703,6 +845,21 @@ export class SamsarClient {
         };
         return this.post('credits/recharge', payload, options);
     }
+    /**
+     * Create a shared-balance Stripe recharge attributed to an external user.
+     */
+    async createExternalCreditsRecharge(externalUser, credits, options) {
+        if (!Number.isFinite(credits) || credits <= 0) {
+            throw new Error('credits must be a positive number');
+        }
+        const payload = {
+            external_user: normalizeExternalUserIdentity(externalUser),
+            input: {
+                credits: Math.round(credits),
+            },
+        };
+        return this.post('external_users/credits/recharge', payload, options);
+    }
     /**
      * Enable or update auto-recharge settings for the API key.
      * Returns a Stripe setup URL when a payment method is required.
@@ -737,6 +894,54 @@ export class SamsarClient {
             query,
         });
     }
+    /**
+     * Poll shared-balance payment status for an external user credit purchase.
+     */
+    async getExternalPaymentStatus(payload, options) {
+        const query = {
+            ...(options?.query ?? {}),
+        };
+        if (payload?.external_payment_id) {
+            query.external_payment_id = payload.external_payment_id;
+        }
+        if (payload?.externalPaymentId) {
+            query.external_payment_id = payload.externalPaymentId;
+        }
+        if (payload?.checkoutSessionId) {
+            query.checkoutSessionId = payload.checkoutSessionId;
+        }
+        if (payload?.paymentIntentId) {
+            query.paymentIntentId = payload.paymentIntentId;
+        }
+        if (payload?.setupIntentId) {
+            query.setupIntentId = payload.setupIntentId;
+        }
+        return this.get('external_users/payment_status', {
+            ...(options ?? {}),
+            query,
+        });
+    }
+    /**
+     * Exchange a login token or verify an auth token against /users/verify_token.
+     */
+    async verifyClientSession(payload, options) {
+        const query = {
+            ...(options?.query ?? {}),
+        };
+        if (payload?.loginToken) {
+            query.loginToken = payload.loginToken;
+        }
+        if (payload?.authToken) {
+            query.authToken = payload.authToken;
+        }
+        if (!query.loginToken && !query.authToken) {
+            throw new Error('loginToken or authToken is required');
+        }
+        return this.get(this.buildRootUrl('users/verify_token'), {
+            ...(options ?? {}),
+            query,
+        });
+    }
     /**
      * Retrieve the status of an asynchronous request by request_id.
      * Defaults to GET /status?request_id={requestId}, but the path can be overridden.
@@ -782,6 +987,16 @@ export class SamsarClient {
         };
         return { ...response, data: normalizedData };
     }
+    /**
+     * Retrieve the status of an external-user-attributed asynchronous request by external request_id.
+     */
+    async getExternalStatus(requestId, options) {
+        const response = await this.getStatus(requestId, {
+            ...options,
+            path: 'external_users/status',
+        });
+        return response;
+    }
     /**
      * Retrieve the status of an image request (maps to GET /image/status).
      */
@@ -879,6 +1094,7 @@ export class SamsarClient {
         const headers = {
             Authorization: `Bearer ${this.apiKey}`,
             'Content-Type': options.body ? 'application/json' : undefined,
+            'x-external-user-api-key': options.externalUserApiKey ?? this.externalUserApiKey,
             ...this.defaultHeaders,
             ...(options.headers ?? {}),
         };
@@ -900,6 +1116,12 @@ export class SamsarClient {
         }
         return url.toString();
     }
+    buildRootUrl(path) {
+        const cleanedPath = path.replace(/^\/+/, '');
+        const baseUrl = trimTrailingSlash(this.baseUrl);
+        const rootUrl = baseUrl.endsWith('/v1') ? baseUrl.slice(0, -3) : baseUrl;
+        return `${rootUrl}/${cleanedPath}`;
+    }
 }
 function trimTrailingSlash(url) {
     return url.replace(/\/+$/, '');
@@ -932,4 +1154,47 @@ function removeEmptyHeaders(headers) {
     }
     return normalized;
 }
+function normalizeExternalUserIdentity(externalUser) {
+    const externalUserId = externalUser.external_user_id ??
+        externalUser.externalUserId;
+    if (!externalUser?.provider || !externalUserId) {
+        throw new Error('externalUser.provider and externalUser.external_user_id are required');
+    }
+    return {
+        provider: externalUser.provider,
+        external_user_id: externalUserId,
+        ...(externalUser.external_app_id || externalUser.externalAppId
+            ? { external_app_id: externalUser.external_app_id ?? externalUser.externalAppId }
+            : {}),
+        ...(externalUser.external_company_id || externalUser.externalCompanyId
+            ? { external_company_id: externalUser.external_company_id ?? externalUser.externalCompanyId }
+            : {}),
+        ...(externalUser.external_account_id || externalUser.externalAccountId
+            ? { external_account_id: externalUser.external_account_id ?? externalUser.externalAccountId }
+            : {}),
+        ...(externalUser.email ? { email: externalUser.email } : {}),
+        ...(externalUser.username ? { username: externalUser.username } : {}),
+        ...(externalUser.display_name || externalUser.displayName
+            ? { display_name: externalUser.display_name ?? externalUser.displayName }
+            : {}),
+        ...(externalUser.avatar_url || externalUser.avatarUrl
+            ? { avatar_url: externalUser.avatar_url ?? externalUser.avatarUrl }
+            : {}),
+        ...(externalUser.metadata ? { metadata: externalUser.metadata } : {}),
+    };
+}
+function buildExternalUserQuery(externalUser) {
+    const normalized = normalizeExternalUserIdentity(externalUser);
+    return {
+        provider: normalized.provider,
+        external_user_id: normalized.external_user_id,
+        external_app_id: normalized.external_app_id ?? undefined,
+        external_company_id: normalized.external_company_id ?? undefined,
+        external_account_id: normalized.external_account_id ?? undefined,
+        email: normalized.email ?? undefined,
+        username: normalized.username ?? undefined,
+        display_name: normalized.display_name ?? undefined,
+        avatar_url: normalized.avatar_url ?? undefined,
+    };
+}
 export default SamsarClient;

package/package.json

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