samsar-js 0.48.11 → 0.48.13

package/README.md

@@ -158,7 +158,7 @@ const websiteEmbedding = await samsar.createEmbeddingFromUrl({
 });
 
 // `levels` controls crawl depth for URL mode: 1 = only listed URLs, 2 = one link hop, 3 = two link hops.
-// The API defaults to 3 levels and caps total crawled pages at 50 per request.
+// The API defaults to 2 levels and caps total crawled pages at 50 per request.
 
 // Create embeddings from already cleaned plain text without crawling
 const cleanTextEmbedding = await samsar.generateEmbeddingsFromPlainText({
@@ -396,7 +396,7 @@ Each method returns `{ data, status, headers, creditsCharged, creditsRemaining,
 
 - Assistant completions are billed from actual request usage. Samsar measures the processed input and generated output, converts usage to credits using the standard `100 credits = $1` rule, and applies a `2.5x` assistant multiplier so text-only and multimodal sessions are priced consistently.
 - 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`) supports `levels` 1-3, defaults to 3, caps total crawled pages at 50 per request, bills actual Firecrawl usage with a `2.5x` crawl multiplier, and then bills the embedding phase with a separate flat `2.5x` multiplier.
+- URL-based embedding creation (`createEmbedding` with `urls`, or `createEmbeddingFromUrl`) supports `levels` 1-3, defaults to 2, caps total crawled pages at 50 per request, bills actual Firecrawl usage with a `2.5x` crawl multiplier, and then bills the embedding phase with a separate flat `2.5x` multiplier.
 - Plain-text embedding creation (`generateEmbeddingsFromPlainText`, `generateExternalEmbeddingsFromPlainText`) skips crawling and charges only the embedding-token cost with a flat `2.5x` multiplier.
 - Token-based routes scale with the amount of content processed. Larger prompts, longer responses, and richer inputs use more credits than short text-only requests.
 - Receipt template creation (`createReceiptTemplate`) and template JSON lookup (`getReceiptTemplateJson`) are free; receipt template query (`queryReceiptTemplate`) costs 50 credits per request.

package/dist/index.d.ts

@@ -1015,6 +1015,52 @@ export interface ExternalCreditsGrantResponse {
     external_user?: ExternalUserSummary | null;
     [key: string]: unknown;
 }
+export interface ExternalUtilityChargeRequest {
+    utility_type?: string;
+    utilityType?: string;
+    type?: string;
+    provider?: string;
+    model?: string;
+    model_id?: string;
+    modelId?: string;
+    text?: string;
+    content?: string;
+    characters?: number;
+    character_count?: number;
+    characterCount?: number;
+    duration_ms?: number;
+    durationMs?: number;
+    duration_seconds?: number;
+    durationSeconds?: number;
+    duration_minutes?: number;
+    durationMinutes?: number;
+    duration_hours?: number;
+    durationHours?: number;
+    firecrawl_credits_used?: number;
+    firecrawlCreditsUsed?: number;
+    pricing_multiplier?: number;
+    pricingMultiplier?: number;
+    multiplier?: number;
+    metadata?: Record<string, unknown>;
+    [key: string]: unknown;
+}
+export interface ExternalUtilityChargeResponse {
+    utilityType?: string;
+    provider?: string | null;
+    model?: string | null;
+    creditsCharged?: number;
+    remainingCredits?: number | null;
+    pricing?: {
+        costUsd?: number;
+        pricingMultiplier?: number;
+        creditsPerDollar?: number;
+        units?: Record<string, unknown>;
+        [key: string]: unknown;
+    } | null;
+    externalUser?: ExternalUserSummary | null;
+    external_user?: ExternalUserSummary | null;
+    [key: string]: unknown;
+}
 export interface ExternalCreditsRechargeResponse extends CreditsRechargeResponse {
     external_payment_id?: string;
     external_user?: ExternalUserSummary | null;
@@ -1305,6 +1351,11 @@ export declare class SamsarClient {
         sessionName?: string;
         metadata?: Record<string, unknown>;
     }, options?: SamsarRequestOptions): Promise<SamsarResult<ExternalAssistantSessionResponse>>;
+    /**
+     * Charge an external user's credits for utility usage such as ElevenLabs TTS/STT or Firecrawl crawl costs.
+     * This is useful when a proxy or integration incurs third-party usage outside the standard Samsar route billing flow.
+     */
+    chargeExternalUserUtilityUsage(payload: ExternalUtilityChargeRequest, externalUser?: ExternalUserIdentity | null, options?: SamsarRequestOptions): Promise<SamsarResult<ExternalUtilityChargeResponse>>;
     /**
      * Create a short-lived external-user login token plus a ready-to-open client login URL.
      */
@@ -1404,7 +1455,7 @@ export declare class SamsarClient {
     createEmbedding(payload: CreateEmbeddingRequest, options?: SamsarRequestOptions): Promise<SamsarResult<CreateEmbeddingResponse>>;
     /**
      * Create a new embedding template from one URL or a list of URLs.
-     * Pass `levels` (1-3) to control crawl depth; the API defaults to 3.
+     * Pass `levels` (1-3) to control crawl depth; the API defaults to 2.
      */
     createEmbeddingFromUrl(payload: CreateEmbeddingFromUrlRequest, options?: SamsarRequestOptions): Promise<SamsarResult<CreateEmbeddingResponse>>;
     /**

package/dist/index.js

@@ -128,6 +128,19 @@ export class SamsarClient {
         }
         return this.post('external_users/utils/assistant_session', body, options);
     }
+    /**
+     * Charge an external user's credits for utility usage such as ElevenLabs TTS/STT or Firecrawl crawl costs.
+     * This is useful when a proxy or integration incurs third-party usage outside the standard Samsar route billing flow.
+     */
+    async chargeExternalUserUtilityUsage(payload, externalUser, options) {
+        const body = {
+            ...payload,
+        };
+        if (externalUser) {
+            body.external_user = normalizeExternalUserIdentity(externalUser);
+        }
+        return this.post('external_users/utils/usage_charge', body, options);
+    }
     /**
      * Create a short-lived external-user login token plus a ready-to-open client login URL.
      */
@@ -625,7 +638,7 @@ export class SamsarClient {
     }
     /**
      * Create a new embedding template from one URL or a list of URLs.
-     * Pass `levels` (1-3) to control crawl depth; the API defaults to 3.
+     * Pass `levels` (1-3) to control crawl depth; the API defaults to 2.
      */
     async createEmbeddingFromUrl(payload, options) {
         return this.post('chat/create_embedding_from_url', payload, options);

package/package.json

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