samsar-js 0.48.10 → 0.48.12

package/README.md

@@ -150,13 +150,29 @@ const embedding = await samsar.createEmbedding({
 // Create embeddings from one URL or a URL list
 const websiteEmbedding = await samsar.createEmbeddingFromUrl({
   name: 'product-docs',
+  levels: 2,
   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.
+// `levels` controls crawl depth for URL mode: 1 = only listed URLs, 2 = one link hop, 3 = two link hops.
+// 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({
+  name: 'product-docs-clean',
+  plain_text: [
+    {
+      url: 'https://example.com/docs/getting-started',
+      title: 'Getting Started',
+      content: 'Cleaned plain text content from the page.',
+    },
+  ],
+});
+
+// The generic createEmbedding wrapper also accepts `urls` plus `levels` on the same route if you prefer one entrypoint.
 
 // Search against an embedding template
 const search = await samsar.searchAgainstEmbedding({
@@ -321,6 +337,22 @@ const externalAssistant = await platform.createExternalAssistantCompletion(
 );
 console.log(externalAssistant.data.output_text);
 
+// Build embeddings for that external user from already cleaned plain text
+const externalEmbedding = await platform.generateExternalEmbeddingsFromPlainText(
+  {
+    name: 'creator-docs-clean',
+    plain_text: [
+      {
+        url: 'https://example.com/creator/faq',
+        title: 'Creator FAQ',
+        content: 'Cleaned plain text content for this external user.',
+      },
+    ],
+  },
+  externalUser,
+);
+console.log(externalEmbedding.data.template_id);
+
 // Fetch their external library
 const library = await platform.listExternalUserRequests(externalUser, { limit: 12 });
 console.log(library.data.requests.length);
@@ -364,7 +396,8 @@ 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`) adds Firecrawl crawl cost to the embedding token cost, then applies Samsar's 100 credits per USD mapping with a `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

@@ -407,6 +407,22 @@ export interface EmbeddingFieldOptions {
     retrievable?: boolean;
 }
 export type EmbeddingUrlInput = string | string[];
+export interface PlainTextEmbeddingEntry {
+    plain_text?: string;
+    plainText?: string;
+    content?: string;
+    text?: string;
+    cleaned_text?: string;
+    cleanedText?: string;
+    markdown?: string;
+    body?: string;
+    url?: string;
+    title?: string;
+    description?: string;
+    language?: string;
+    [key: string]: unknown;
+}
+export type PlainTextEmbeddingInput = string | PlainTextEmbeddingEntry | Array<string | PlainTextEmbeddingEntry>;
 export type EmbeddingFieldOptionsInput = Record<string, EmbeddingFieldOptions> | Array<EmbeddingFieldOptions & {
     key?: string;
     field?: string;
@@ -424,6 +440,7 @@ export interface CreateEmbeddingRequest {
     records?: Array<Record<string, unknown>>;
     urls?: EmbeddingUrlInput;
     url?: string;
+    levels?: number;
     name?: string;
     embedding_name?: string;
     template_name?: string;
@@ -434,6 +451,33 @@ export interface CreateEmbeddingRequest {
 export interface CreateEmbeddingFromUrlRequest {
     urls?: EmbeddingUrlInput;
     url?: string;
+    levels?: number;
+    name?: string;
+    embedding_name?: string;
+    template_name?: string;
+    field_options?: EmbeddingFieldOptionsInput;
+    fieldOptions?: EmbeddingFieldOptionsInput;
+    [key: string]: unknown;
+}
+export interface GenerateEmbeddingsFromPlainTextRequest {
+    plain_text?: PlainTextEmbeddingInput;
+    plainText?: PlainTextEmbeddingInput;
+    plain_texts?: PlainTextEmbeddingInput;
+    plainTexts?: PlainTextEmbeddingInput;
+    texts?: PlainTextEmbeddingInput;
+    documents?: PlainTextEmbeddingInput;
+    items?: PlainTextEmbeddingInput;
+    entries?: PlainTextEmbeddingInput;
+    content?: string;
+    text?: string;
+    cleaned_text?: string;
+    cleanedText?: string;
+    markdown?: string;
+    body?: string;
+    url?: string;
+    title?: string;
+    description?: string;
+    language?: string;
     name?: string;
     embedding_name?: string;
     template_name?: string;
@@ -449,6 +493,8 @@ export interface CreateEmbeddingResponse {
     input_url_count?: number;
     processed_url_count?: number;
     firecrawl_credits_used?: number;
+    crawl_levels?: number;
+    max_links?: number;
     skipped_urls?: EmbeddingUrlIssue[];
     crawl_errors?: EmbeddingUrlIssue[];
     structured_fields?: EmbeddingStructuredField[];
@@ -969,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;
@@ -1083,6 +1175,10 @@ export interface ExternalAssistantSetSystemPromptResponse extends AssistantSetSy
     external_user?: ExternalUserSummary | null;
     externalUser?: ExternalUserSummary | null;
 }
+export interface ExternalCreateEmbeddingResponse extends CreateEmbeddingResponse {
+    external_user?: ExternalUserSummary | null;
+    externalUser?: ExternalUserSummary | null;
+}
 export interface VerifyClientSessionInput {
     loginToken?: string;
     authToken?: string;
@@ -1255,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.
      */
@@ -1271,6 +1372,11 @@ export declare class SamsarClient {
      * The owning Samsar account's configured assistant model is used internally.
      */
     createExternalAssistantCompletion(payload: AssistantCompletionRequest, externalUser?: ExternalUserIdentity | null, options?: SamsarRequestOptions): Promise<SamsarResult<AssistantCompletionResponse>>;
+    /**
+     * Create a new embedding template for an external user from already cleaned plain text.
+     * This skips crawling and bills the external user's credits only.
+     */
+    generateExternalEmbeddingsFromPlainText(payload: GenerateEmbeddingsFromPlainTextRequest, externalUser?: ExternalUserIdentity | null, options?: SamsarRequestOptions): Promise<SamsarResult<ExternalCreateEmbeddingResponse>>;
     /**
      * Translate an existing video session into a new language.
      * Creates a new session_id and queues generation steps for lip sync + transcription + video render.
@@ -1344,12 +1450,19 @@ export declare class SamsarClient {
     createAssistantCompletion(payload: AssistantCompletionRequest, options?: SamsarRequestOptions): Promise<SamsarResult<AssistantCompletionResponse>>;
     /**
      * Create a new embedding template from either a JSON array (`records`) or a URL input (`urls`).
+     * URL mode also accepts `levels` (1-3) to control crawl depth.
      */
     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 2.
      */
     createEmbeddingFromUrl(payload: CreateEmbeddingFromUrlRequest, options?: SamsarRequestOptions): Promise<SamsarResult<CreateEmbeddingResponse>>;
+    /**
+     * Create a new embedding template from already cleaned plain text.
+     * This skips crawling and uses the same compatible template format as the JSON and URL routes.
+     */
+    generateEmbeddingsFromPlainText(payload: GenerateEmbeddingsFromPlainTextRequest, options?: SamsarRequestOptions): Promise<SamsarResult<CreateEmbeddingResponse>>;
     /**
      * Update an existing embedding template with additional records.
      */

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.
      */
@@ -167,6 +180,19 @@ export class SamsarClient {
         }
         return this.post('external_users/assistant/completion', body, options);
     }
+    /**
+     * Create a new embedding template for an external user from already cleaned plain text.
+     * This skips crawling and bills the external user's credits only.
+     */
+    async generateExternalEmbeddingsFromPlainText(payload, externalUser, options) {
+        const body = {
+            ...payload,
+        };
+        if (externalUser) {
+            body.external_user = normalizeExternalUserIdentity(externalUser);
+        }
+        return this.post('external_users/generate_embeddings_from_plain_text', 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.
@@ -605,16 +631,25 @@ export class SamsarClient {
     }
     /**
      * Create a new embedding template from either a JSON array (`records`) or a URL input (`urls`).
+     * URL mode also accepts `levels` (1-3) to control crawl depth.
      */
     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.
+     * 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);
     }
+    /**
+     * Create a new embedding template from already cleaned plain text.
+     * This skips crawling and uses the same compatible template format as the JSON and URL routes.
+     */
+    async generateEmbeddingsFromPlainText(payload, options) {
+        return this.post('chat/generate_embeddings_from_plain_text', payload, options);
+    }
     /**
      * Update an existing embedding template with additional records.
      */

package/package.json

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